#21233: docs: clarify bind=lan non-loopback access requires wss or tunnel (#21158)
docs
gateway
size: XS
Cluster:
Gateway Resilience and Configuration
## Summary Refs #21158.
Add documentation guidance for the `bind=lan` / non-loopback case where direct plaintext WebSocket URLs are rejected by security checks.
## Changes
`docs/cli/gateway.md`: clarified that direct non-loopback targets should use `wss://` (or SSH tunnel to loopback), and that plain `ws://<non-loopback>` is blocked.
- `docs/gateway/troubleshooting.md`: added explicit troubleshooting notes/signatures for:
- plaintext non-loopback `ws://` rejection
- when to enable `gateway.tls.enabled=true`
- using loopback/SSH tunnel for local operator checks
Refs #21158.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds documentation clarifying that direct non-loopback WebSocket connections must use `wss://` or SSH tunneling, aligning with the security checks in `src/gateway/net.ts:isSecureWebSocketUrl()` that block plaintext `ws://` to non-loopback addresses (line 429-430). The changes accurately describe the error signature users see when the security check fails and provide correct remediation guidance.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no risk
- Documentation-only changes that accurately describe existing security behavior. The guidance correctly references `gateway.tls.enabled=true` (verified in `src/config/types.gateway.ts:3-13`), matches the actual error message from `src/gateway/call.ts:161`, and provides valid workarounds (wss:// or SSH tunnel) that align with the security check implementation in `src/gateway/net.ts:413-431`
- No files require special attention
<sub>Last reviewed commit: 4fbac9a</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#22056: fix(gateway): use loopback for self-connections regardless of bind ...
by usedhonda · 2026-02-20
82.9%
#22110: fix(tools): prefer loopback for internal tool-to-gateway RPC calls
by pierreeurope · 2026-02-20
81.1%
#21436: fix(gateway): plaintext ws:// blocked for Docker bind=lan (SECURITY...
by xinhuagu · 2026-02-19
80.7%
#21842: fix(gateway-cli): use wss:// scheme when gatewayTls is enabled
by hydro13 · 2026-02-20
79.8%
#19026: fix(gateway): use loopback for local CLI-to-gateway connections
by Phineas1500 · 2026-02-17
79.1%
#22682: fix(gateway): [P0] status probe ignores gateway.tls.enabled — hardc...
by mahsumaktas · 2026-02-21
79.1%
#21741: fix(gateway): allow plaintext ws:// for Docker/private network addr...
by Joe3112 · 2026-02-20
78.5%
#14277: fix(CLI): Use wss for probeUrl, when gateway has tls enabled
by tha80 · 2026-02-11
78.2%
#23735: Gateway: add first-class wss validation and remote TLS guidance
by bmendonca3 · 2026-02-22
77.5%
#21256: fix: treat ws:// to Tailscale addresses as secure when bind=tailnet
by jessewunderlich · 2026-02-19
76.8%