Relay Architecture Spec
This is the compact reference for the Hermes-Relay connection model, pairing/session lifecycle, transport boundaries, and operator-owned controls.
Open the full-size spec image.
Deployment boundary
Hermes-Relay is designed for operator-owned infrastructure. Remote access should use Tailscale, another VPN, or HTTPS/WSS termination controlled by the operator. Plain ws:// is treated as a trusted LAN/VPN mode only.
Connection paths
| Surface | Path | Auth model | Notes |
|---|---|---|---|
| Chat | Phone/desktop → Hermes API Server | Hermes API bearer / API server auth | Uses HTTP/SSE and does not require the relay path. |
| Voice | Phone/desktop → Relay voice routes | Relay session grant or Hermes API bearer | Non-loopback API-bearer voice requests require HTTPS unless the operator enables the temporary insecure dev toggle. |
| Bridge + terminal | Phone/desktop ↔ Relay Server | Relay pairing code → session token + grants | High-trust path for terminal, media, bridge, and device-control surfaces. |
| Management routes | Host-local only | Loopback caller | Pairing registration, minting, relay security toggles, and bridge status stay loopback-only. |
Pairing / session lifecycle
- Mint — the Hermes host creates a short-lived QR/code and embeds relay/API endpoint metadata.
- Exchange — the client proves possession by sending the code in its first auth envelope over the relay connection.
- Token — the relay consumes the code and issues an expiring bearer token with per-channel grants.
- Revoke — paired devices can be inspected, extended, limited, or revoked from app/dashboard routes.
Implemented controls
- Pairing codes are temporary and one-shot.
- Relay sessions use scoped bearer tokens with feature-specific grants and expiries.
- Terminal, bridge, voice, media, clipboard, and profile-write paths check active grants.
- Non-loopback API-bearer voice calls require HTTPS by default.
- Pairing and management routes are loopback-only.
- Bridge/device-control actions require user-visible Android toggles and OS-level permissions before acting.
Operational constraints
- Relay tokens are bearer credentials; protect them like API keys.
- Bridge and terminal grants are high-trust capabilities.
- Plain WebSocket is for trusted LAN/VPN only.
- Public exposure should sit behind TLS and firewall or VPN controls.
- Unknown or stale paired devices should be revoked.