Reach: WebSocket
A key paired by reach-pair.v1 whose row grants ws (every client row by default). The helper's accept rule runs after the TLS handshake and before a byte.
Living doc, checked against the code 2026-11-14
reach-ws.v1 — the frontend protocol’s WebSocket carried over reach, one QUIC stream per WebSocket
- Status: accepted; public, built.
publicis its label in the API catalog. - Scope: how a paired key reaches the gateway’s frontend WebSocket from another network. The frontend protocol 5 crosses the WebSocket unchanged. This contract adds no frame.
- Off by default. The helper serves this ALPN only with
[reach] enabled = trueand[reach] helper_wsset.
Who may open it
It closes any other key with the codes in
reach-pair.v1’s accept rule: 2 unpaired, 3 revoked, 4 role,
5 attest. A delegated agent key holding a one-shot admission for ws (from vulpine/delegate/1, an owner ALPN)
may also open it, for that one connection.
The wire
- Dial the gateway’s
EndpointId(from the pairing) on ALPNvulpine/ws/1. - Open one bidirectional stream per WebSocket. A connection may carry many. Each is independent, and a failed stream ends alone.
- On the stream, speak a WebSocket client exactly as on a TCP socket: the HTTP/1.1
Upgraderequest to/, then WebSocket frames (RFC 6455) both ways. The helper copies the stream’s bytes to the gateway’s loopback ws port and back, and reads, rewrites and frames nothing. A FIN on one side finishes the other side’s write half. - If the helper cannot reach the gateway’s port, it resets the stream and stops reading it with application code
1(refused). The connection and its other streams carry on.
The bytes are a plain WebSocket, so the gateway’s own rules apply:
- The Origin guard. The gateway sees a client on loopback. A native client sends no
Originand is accepted. A page’sOriginmust be a loopback or Tauri origin or be listed in[frontend] allowed_origins, or the upgrade is answered403(crates/voice_gateway/src/browser_origin.rs). - Protocol 5. The gateway sends
hellofirst and the client answers with its ownhello(protocol_version: 5), as for any frontend. The client may name the route in its hello’scapabilities.reach:{route: "iroh", via: "direct"|"relay", rtt_ms, from}, closed words and a fleet label, never an address. The Admin’s Live sessions row shows it. - Audio is the frontend protocol’s binary PCM16 frames inside the WebSocket. For speech over a lossy or relayed path, reach-voice.v1 carries the same session with Opus datagrams. A client that is refused there falls back to this ALPN.
What Vulpine’s own clients do (not normative)
vulpine-reach open ws carries its stdin and stdout over one such stream; the Admin’s onboarding check opens one. It
writes reach_path via=<relay|direct> rtt_ms=<n> on stderr at open and at every path switch.
vulpine-reach voice relay falls back to this ALPN when vulpine/voice/1 is refused or off. The loopback Client Core
behind it is the same either way.
Compatibility
- Nothing on the stream belongs to reach, so a change to the frontend protocol is that protocol’s change
(
PROTOCOL_VERSION), never this ALPN’s. - Anything reach would add to the stream (a header, a framing) takes
vulpine/ws/2.
See also
- API surfaces: this ALPN’s row and its stability label.
- The frontend protocol’s JSON Schema: frontend.v5.schema.json.
- ADR 0053.