---
title: "Reach: WebSocket"
description: "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."
type: "living"
source: "docs/contracts/reach-ws.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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**. `public` is 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 = true` and `[reach] helper_ws` set.

## Who may open it

It closes any other key with the codes in
[reach-pair.v1's accept rule](/docs/contracts/reach-pair.v1#after-pairing-the-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

1. Dial the gateway's `EndpointId` (from the pairing) on ALPN `vulpine/ws/1`.
2. Open one bidirectional stream per WebSocket. A connection may carry many. Each is independent, and a failed stream
   ends alone.
3. On the stream, speak a WebSocket client exactly as on a TCP socket: the HTTP/1.1 `Upgrade` request 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.
4. 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 `Origin` and is accepted. A
  page's `Origin` must be a loopback or Tauri origin or be listed in `[frontend] allowed_origins`, or the upgrade is
  answered `403` (`crates/voice_gateway/src/browser_origin.rs`).
- **Protocol 5.** The gateway sends `hello` first and the client answers with its own `hello` (`protocol_version: 5`),
  as for any frontend. The client may name the route in its hello's `capabilities.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](/docs/contracts/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](/docs/reference/api-surfaces): this ALPN's row and its stability label.
- The frontend protocol's JSON Schema: frontend.v5.schema.json.
- ADR 0053.
