Start at the README — it carries the three quick starts and the
full VOCAGATEWAY_* table. These pages go deeper on one topic each.
| Page | Read it when |
|---|---|
| deployment.md | Choosing between native macOS, native Linux, and Docker; running at login; backups; the portable CPU service and cuda/vulkan Compose profiles; where the phone reaches the host |
| configuration.md | You need the exact value of a path, an environment variable, or the pairing QR payload |
| desktop-embed.md | Embedding the gateway in a desktop app (Planned); Pairable vs Ready; Compose image pin; platform launch notes |
| tailscale.md | You want private HTTPS to the gateway without opening a port |
| troubleshooting.md | Something is failing and you want the symptom, not the theory |
| models.md | Picking a model: all 58 in the catalog, what each speaks, and a reverse index from 108 languages back to the models that cover them |
- Docker on Linux — Compose quick start,
then
.env.examplefor every knob. On the default bridge network, setVOCAGATEWAY_PUBLIC_URLbefore you scan the pairing QR. - Apple silicon Mac — native macOS quick start. MLX Audio and WhisperKit are the fast paths; Docker Desktop cannot reach them.
- Linux desktop or home server, no container — native Linux quick start.
In all three, the gateway is live before any model exists. GET /health/ready
answers 503 until you download and select one in the WebUI.
Gateway mode is not on-device processing: audio leaves the phone for the machine
you chose. Keep port 8765 off the public internet. Use a trusted LAN,
Tailscale Serve, or an
HTTPS reverse proxy with a real
certificate. HTTP protects neither the bearer token nor the recording.
models.md is generated — run uv run scripts/generate_model_docs.py rather
than editing it; a test asserts --check. Everything else on this page is
hand-written. AGENTS.md has the repository conventions.