Skip to main content
Relay is a zero-knowledge room router. When a PC and a paired device cannot connect directly, each opens a full-duplex WebSocket (/ws) to the Relay, and Remote v2 control, RPC, event, and binary frames travel end-to-end encrypted between the device and the PC. Relay does not decrypt, authorize, store, or log any business payload, and it provides no mobile web UI and no business API.
Relay only forwards. To actually host sessions and Agents on a server, use the Self-hosted headless runtime.

​
Quick start

The container image is multi-arch (linux/amd64, linux/arm64) and is updated with every release:
Compose publishes only 127.0.0.1:9700 by default. Keep that default and run Caddy or Tailscale Serve on the same machine. Image tag rules match the headless runtime: rc follows the latest release candidate, and latest points only to stable releases.

​
Endpoints

/api/rooms/* is a reserved compatibility bridge, not the primary transport for native mobile clients.
There is no /api/v2/info on Relay—that is the authoritative runtime gateway’s endpoint. Mixing up the two addresses is a common troubleshooting mistake.

​
Public HTTPS (Caddy)

Point a DNS record at the host, then start the Caddy profile:
Caddy proxies /ws, /health, and /api/* on the same HTTPS origin; the root path and static asset paths return 404. Clients derive wss://relay.example.com/ws from that.

​
Private Tailnet (Tailscale Serve)

Use the HTTPS address shown by tailscale serve status as the Relay origin. Serve terminates tailnet HTTPS and proxies the WebSocket upgrade, and both ends still use /ws.

​
Key limits

Every Relay limit is bounded. The defaults are:

​
Zero-knowledge verification

After deploying, you should be able to confirm that Relay really cannot see business data:
  1. Connect both ends through Relay and complete one business operation (for example, reading a session).
  2. Inspect the Relay logs; they should contain only routing, counts, and timing metadata.
  3. Confirm the logs contain no tokens, pairing codes, private keys, prompts, file paths, terminal contents, Git diffs, provider settings, raw ciphertext, or nonces.

​
Optional push

Relay can be configured with an operator-owned push adapter, off by default. The relevant environment variables are VIBEX_RELAY_PUSH_PROVIDER, VIBEX_RELAY_PUSH_AUTH_TOKEN, VIBEX_RELAY_PUSH_ADAPTER_URL, and VIBEX_RELAY_PUSH_ADAPTER_AUTH_TOKEN.

​
Security recommendations

  • Keep the loopback binding and publish through a controlled HTTPS/WSS entry point or a Tailnet.
  • Do not expose plaintext HTTP to the public internet.
  • Validate Host and Origin independently, and never use * for CORS.
  • Do not treat a room id as an authorization credential.