Protocol Overview
WebSocket protocol specification for TermPod — frame types, connection lifecycles, and transport details.
TermPod uses WebSocket for all communication between clients (desktop, mobile) and the relay. The protocol uses two frame types:
- Binary frames: Terminal I/O data (high frequency, low overhead)
- Text frames: JSON control messages (low frequency, structured)
WebSocket Endpoints
There are two WebSocket endpoints:
Session WS (/sessions/:id/ws)
Per-session connection to a TerminalSession Durable Object. Handles binary terminal data relay and scrollback.
Client Relay (TerminalSession DO)
│ │
├─── GET /sessions/:id/ws ──────────────►│
│ Headers: Authorization: Bearer <JWT>
│ │
│◄── 101 Switching Protocols ────────────┤
│ │
├─── TEXT: { type: "hello", ... } ──────►│
│ │
│◄── TEXT: { type: "session_info" } ─────┤
│◄── TEXT: { type: "ready" } ────────────┤
│ │
│ ═══ E2E key exchange ═══ │
│ │
│◄── TEXT: { type: "key_exchange" } ─────┤
├─── TEXT: { type: "key_exchange_ack" } ►│
│ │
│ ═══ encrypted streaming ═══ │
│ │
│◄── BINARY: [0xE0] + encrypted data ───┤
├─── BINARY: [0xE0] + encrypted input ──►│Device WS (/devices/:deviceId/ws)
Per-device connection to the User Durable Object. Handles session discovery, management, WebRTC signaling, and multiplexed terminal data forwarding.
Client Relay (User DO)
│ │
├─── GET /devices/:id/ws ───────────────►│
│ ?token=JWT │
│ │
│◄── 101 Switching Protocols ────────────┤
│ │
├─── TEXT: { type: "auth", token } ─────►│
│◄── TEXT: { type: "auth_ok" } ──────────┤
│ │
├─── TEXT: { type: "hello", ... } ──────►│
│◄── TEXT: { type: "hello_ok", ... } ────┤
│ │
│ ═══ device control plane active ═══ │
│ │
├─── TEXT: { type: "list_sessions" } ───►│
│◄── TEXT: { type: "sessions_list" } ────┤Transport Priority
TermPod uses three transports in order of preference:
- Local WebSocket (Bonjour) — Same LAN, ~1-5ms. Desktop advertises
_termpod._tcpvia mDNS. Single multiplexed connection per device. Free tier. - WebRTC DataChannel — Different networks, ~10-30ms. STUN-based P2P (free). TURN relay requires Pro plan. Signaling routed through Device WS.
- Relay Device WS — Fallback, ~30-80ms. Requires Pro plan on hosted relay. Always connected for signaling and session management regardless of plan.
All transports use the same multiplexed binary frame format.
Versioning
The version field in the hello message enables protocol evolution. Current version: 1.