Production Deployment Architecture — Four Trust Tiers

Audience: future Swift / iOS and Kotlin / Android developers + DevOps engineers evaluating where VSRelay traffic flows for App Store submission and infrastructure decisions.

TL;DR

VSRelay ships with four trust tiers, each with different cost / privacy / convenience tradeoffs. The native iOS / Android app supports all four through a first-run picker. Most users pick Tier 1 (easy + private); power users pick Tier 2 or 3.

Tier 0 — Plaintext relay (today)

What’s running: wss://relay.vsrelay.dev/relay/room/<roomId>/{client,extension} (vsrelay.dev is retired) with no payload encryption beyond standard TLS. The relay sees every prompt, every Claude response, every file read/write, every terminal output. Suitable for one developer (the project author) testing locally. NOT shippable to App Store with a straight face.

Room admission: even at Tier 0, the relay performs authenticated admission — a WS upgrade is only admitted when the roomId exists in Supabase AND sha256(presented_deviceToken) matches the stored hash (via relay_lookup_room SECURITY DEFINER RPC). Connections fail-closed on any mismatch. Payload bodies are still forwarded transparently; admission validates who may enter, not what they say.

Where it is: the current packages/relay/ runtime. Open-source. Self-host-friendly even today, but encryption gap means it’s only acceptable for local-network use without a trust commitment to the operator.

App Store implications: the native app COULD ship against Tier 0, but its privacy disclosures would have to honestly state “your code, prompts, and Claude responses flow through a third-party relay server we operate, in plaintext over TLS.” Reviewers would likely accept this with the right disclosure, but the user experience would erode trust on day one. Hence Tier 0 is dev-only by convention.

Tier 1 — E2E-encrypted cloud relay (Phase C, production default)

What’s running: wss://relay.vsrelay.dev/relay/room/<roomId>/{client,extension} BUT the payloads between PWA / native client and the extension are encrypted end-to-end using NaCl secretbox (or equivalent). Keys are established during a QR-code pairing flow at first run. The relay is a dumb pipe that routes ciphertext.

Server visibility: the relay sees:

• The roomId (a routing label).
• The ciphertext byte stream.
• Heartbeat / ping metadata.

The relay does NOT see:

• Prompts.
• Claude responses.
• File contents.
• Terminal output.
• Any user-content payload.

Even if the relay is subpoenaed or compromised, the operator has nothing useful to hand over.

Pairing flow:

1. User installs the native app.
2. User opens VS Code with the VSRelay extension.
3. Extension command “Show Pairing QR” displays a QR code containing room ID + public key + initial nonce.
4. User scans with native app. Phone generates its own keypair, exchanges public keys via the room, sends encrypted hello.
5. Extension verifies, stores phone’s public key, completes pair.
6. Subsequent connections are end-to-end encrypted using the established session keys. Forward secrecy via per-session ephemeral keys.

App Store implications: trivially clean. The submission text in RecoveryActions is true under Tier 1. The reviewer cares about the device behavior, not the server topology. The native app downloads encrypted bytes + renders state — nothing about its compiled logic changes post-review.

Status: designed in this brainstorm, NOT YET BUILT. Phase C is its own multi-week design + spec + implementation cycle.

Tier 2 — Bring-your-own relay

What’s running: the user runs the same packages/relay/ binary on their own server — VPS, home NAS, Tailscale-linked machine, anywhere reachable from both phone and laptop. The native app is configured with a Relay URL setting pointing at the user’s server. The user’s relay is presumably also Tier 1-encrypted (we ship the relay with E2E support whether we host it or they do).

Server visibility: still ciphertext under Tier 1 encryption. The user trusts their own server operator (themselves).

App Store implications: the relay URL is a user-configurable setting. No server operator implications for our submission — we’re not running anything for these users.

Status: the relay binary is open-source TODAY (already in packages/relay/). What’s missing is the Tier 1 encryption layer and a polished setup wizard. Both arrive in Phase C / future phases.

Tier 3 — Local network only

What’s running: phone connects directly to the laptop over LAN. The extension’s local HTTP/WS server (0.0.0.0:18100 today) accepts the connection. The relay is not involved. mDNS or QR-pair handles the discovery + auth.

Server visibility: zero — there is no server. Traffic never leaves the LAN.

App Store implications: the native app needs the local-network permission on iOS (NSLocalNetworkUsageDescription in Info.plist) and the equivalent on Android. The OS prompts on first connect. Otherwise no special review concerns.

Status: the underlying transport works today (the PWA uses it via Vite proxy in dev mode). Missing pieces: mDNS discovery, QR-pair onboarding, native-side LAN connection UI. Phase D or later.

Why all four exist

The native iOS / Android app supports all four through one renderer. The selection is a first-run picker:

How do you want to connect?
  ● Easy: VSRelay cloud, end-to-end encrypted          ← Tier 1
  ○ Advanced: I run my own relay server               ← Tier 2
  ○ Local network only (home WiFi)                    ← Tier 3

The protocol shapes (including RecoveryActions v1) are orthogonal to the trust tier — the same wire shapes work over plaintext (T0), encrypted bytes (T1), self-hosted (T2), or local (T3).

Sequencing — what ships when

1. Tier 0 — exists today. Dev state. Not for users.
2. RecoveryActions v1 — ships in current PR (2026-05-21). Independent of tier.
3. Tier 1 E2E encryption — Phase C, multi-week. The gate before native ship.
4. Tier 2 BYO relay polish — Phase D. Docker image, setup docs, Tailscale guide.
5. Tier 3 local network mode — Phase E. mDNS / QR-pair onboarding.
6. Native iOS + Android — Phase G. Ships against Tiers 1+2+3.

Bandwidth + cost reality

For Tier 1 (which is the only tier with operator-side cost concerns):

• Average message size: <5 KB (prompts, session events, file diffs).
• Average active session: ~100 messages/minute peak, idle most of the time.
• Per-user daily bandwidth: <100 MB.
• 10,000 daily active users: ~1 TB/day total.

Cloudflare Durable Objects handle this with near-zero ops effort and per-room pricing — well under $100/month at 10k DAU. Bandwidth is not the bottleneck. Trust acquisition is. Encryption pays the trust cost once.

Cross-references

• README — overview + per-module map
• Relay — current relay’s transparent-forwarder semantics
• RecoveryActions — v1 recovery surface (this PR)
• Spec: docs/superpowers/specs/2026-05-21-recovery-actions-protocol-v1-design (source repo)