Dev Tunnels or ngrok WebSocket not working: connection checks

Does the WebSocket work locally?

Connect to the exact local WebSocket path from the agent’s environment first. A successful HTTP home page does not prove the WebSocket endpoint works. Check the listener, port and expected subprotocol; a container’s localhost may refer to a different machine.

An April 2025 Dev Tunnels report describes anonymous and token-header WebSocket timeouts while CLI port forwarding worked. No diagnosis is published in that report, so it does not establish that every Dev Tunnels WebSocket connection fails.

Which public WebSocket address should I use?

Use the public wss:// host and the app’s actual WebSocket path for a secure browser connection. Check that client configuration has not retained localhost, an old tunnel address or a development port. The app may need explicit configuration for its public endpoint.

ngrok currently documents WebSockets through HTTP endpoints without special configuration. Its HTTP endpoint can carry ordinary HTTP and WebSocket traffic on the same app port; a separate raw TCP endpoint is not a general requirement.

Did the connection open or fail during the handshake?

Inspect the browser Network WebSocket entry and the app logs. For an HTTP/1.1 upgrade, 101 Switching Protocols indicates the handshake succeeded. A login redirect, 401, 403, missing-path response or upstream error needs a different fix from a connection that opens and later closes.

A browser error event alone does not identify the root cause. If the socket opens, record when it closes and the available close code, then examine app lifecycle, network interruption and heartbeat behavior. ngrok’s documented inspection covers the initial 101 response, not subsequent WebSocket messages.

Can browser WebSockets send a tunnel authorization header?

The browser WebSocket constructor accepts a URL and optional subprotocols; it has no arbitrary-header argument. A custom tunnel-header solution available to a server-side client cannot simply be copied into browser JavaScript.

Review tunnel access separately from app authentication. A private-tunnel login redirect can interrupt the handshake. Do not put long-lived credentials in a public URL or disable authentication as a blanket fix. Only choose anonymous tunnel access when the app is intended to be reachable publicly and protects its own data.

Should I disable Origin or subprotocol checks?

Keep deliberate application checks. Verify the browser’s actual Origin and requested subprotocol against the app’s expected values. Allow the intended development origin where appropriate rather than accepting every origin.

A new public address can change the browser origin even when the local app is unchanged. Diagnose the handshake and server rejection before assuming a tunnel transport fault; do not treat ordinary HTTP CORS settings as a universal WebSocket repair.

Can I test WebSockets with Groundhog?

Groundhog forwards WebSocket upgrades to a connected local HTTP app and passes Origin through unchanged. Verify a small message exchange and a clean close, not only a successful home page or handshake.

Groundhog is free and best effort with workspace and shared-service limits. Changing providers will not correct the wrong app path, an app-origin rejection or an unavailable local listener. It is not a replacement for arbitrary raw TCP workflows.

Sources

Sources reviewed 2026-10-14. Provider behavior and limits can change.