Core Concepts
VSRelay is small but precise. Five concepts to know.
Relay + room
Every paired phone ↔ extension session is a room, validated against a Supabase identity layer. The relay (relay.vsrelay.dev) is a transparent forwarder: it routes who-talks-to-whom, never inspects message bodies, never stores your prompts or code or workspace paths.
When the extension activates, it opens an outbound WebSocket to the relay and joins your room. When the phone opens the PWA, it joins the same room. The relay forwards bytes between them. That’s it.
Extension
The VSRelay extension is a VS Code / Cursor extension that:
- Embeds an HTTP + WebSocket server on port 18100 (for LAN-direct mode).
- Connects outbound to the cloud relay (for remote mode).
- Watches Claude Code’s JSONL session files and re-emits session events as protocol messages.
- Exposes a tiny set of plane-controllers (terminals, files, diagnostics, workspace) over the protocol.
Planes
A plane is a thin protocol surface for one editor concern. Each plane has its own capability gate, its own wire shapes, and its own renderer in the PWA.
| Plane | What you do from the phone |
|---|---|
| Sessions | List sessions, watch one, send prompts, approve / reject permissions |
| Files | Browse the workspace tree, view files, edit + save with optimistic concurrency |
| Diagnostics | View VS Code’s Problems panel, reveal a problem in the editor |
| Terminals | List terminals, reveal one, spawn a managed terminal, type into it |
| Workspace | Open a new workspace, list available roots |
Planes are additive — new ones ship in extension updates without protocol breakage.
Capabilities
Clients (PWA, native iOS, native Android) announce which capabilities they speak in their auth message. The extension only sends plane events the client claimed to support. New capabilities ship as additive strings; unknown capabilities are silently filtered server-side.
Current capabilities include session_subscriptions, terminal_observe, terminal_control, diagnostics_observe, files_observe, files_control, workspace_activation, ssh_key_setup, turn_status_observe.
Trust tiers
You choose how phone ↔ extension traffic flows:
- Tier 1 — Trusted cloud relay (default). Traffic goes through
relay.vsrelay.dev. TLS in transit; room-validated against Supabase; relay never inspects bodies. - Tier 2 — BYO relay. Self-host the relay binary on your own infrastructure. VSRelay’s hosted relay is not in the path.
- Tier 3 — LAN-only. Phone connects directly to the extension over your local network. No server in the path at all.
Tier 0 (E2E-encrypted cloud relay where bytes are ciphertext to the relay) is on the roadmap and not yet shipped.
App-store resilience
VSRelay is protocol-first. Native clients (iOS, Android) render server-provided state; they don’t own dynamic recovery logic. When a Claude Code regression needs a new recovery flow, the extension + relay ship the new action description as data — the app’s pre-built renderer displays it without a binary update.
See Native Integration for the full contract.