Glossary

Every name and acronym you'll hear, in one place. Keep this open in a tab.

The components

Term	What it is
sudoedge	The small Python program that runs on the Raspberry Pi in the home. Captures mic, plays speaker, runs first-time setup. Native process, not a container.
sudo-api	The cloud web server (aiohttp). Serves the website, the /v1/* API, and — importantly — spawns the per-user agent containers itself. Code: cloud/api/.
hermes	The AI agent. We run upstream nousresearch/hermes-agent unmodified, one container per family account. This is "the brain."
voice-bridge	The cloud worker that turns speech↔text for voice. Does STT (speech→text), calls hermes, does TTS (text→speech). Code: cloud/voice_bridge/.
livekit-server	The WebRTC media server (an "SFU") that carries audio between the Pi and voice-bridge. Off-the-shelf (livekit/livekit-server).
Caddy	The web server on the VPS that terminates HTTPS and routes traffic to the right service. Runs natively on the host (systemd), not in a container. Config: caddy/Caddyfile.
Supabase	Hosted Postgres and auth. All durable state lives here; it also issues the login tokens for the browser.
OpenRouter	The gateway we use to reach the actual LLM. The API key is set once, globally, by an admin.
Deepgram	Speech-to-text provider used by voice-bridge (configurable).
Twilio	Provider for the WhatsApp Business channel (one shared number for everyone).
Grafana / Loki / promtail	Observability stack. Grafana = dashboards, Loki = log storage, promtail = ships container logs into Loki.

The three surfaces

Term	What it is
Voice	Talking to the Pi in the home. Audio flows over WebRTC via LiveKit.
Chat	The browser chat at sudohomes.com/chat. Uses a persistent SSE stream + fire-and-forget POSTs.
WhatsApp	Messaging the shared Twilio WhatsApp number from your phone.

hermes concepts

Term	What it is
Platform / adapter	hermes' word for an integration surface. Each of our three surfaces is a hermes "platform." Voice/chat use api_server + plugins; WhatsApp/chat/voice each also have a bundled plugin adapter.
Plugin	Code bind-mounted into hermes at /opt/data/plugins/ that adds a platform without forking the image. We ship three: twilio_whatsapp, sudo_chat, sudo_voice.
api_server	hermes' built-in HTTP platform exposing /v1/chat/completions. Voice (and chat in V0) call it directly.
send_message(target=…)	How the agent proactively sends a message out a chosen surface.
cronjob(deliver=…)	How the agent schedules a message for later, delivered out a chosen surface.
Memory (MEMORY.md / USER.md)	The agent's persistent memory files, stored in its per-user volume.
Session key	X-Hermes-Session-Key: user_<uuid> — pins a request to a family's agent session.

Provisioning & infra

Term	What it is
provisioner	The logic inside sudo-api (cloud/api/provisioner.py) that spawns/stops per-user hermes containers via the host's docker socket. Not a separate service.
ensure_runtime()	"Make sure this family's agent container is running, and wait until it's healthy."
_SEED_AND_EXEC	The boot script the provisioner injects so each hermes container writes its config on every start, then hands off to upstream's entrypoint.
API_SERVER_KEY	The per-user bearer for calling a family's hermes, derived as HMAC(JWT_SECRET, user_id) — never stored, recomputed each call.
PROVISIONER_INTERNAL_TOKEN	The shared bearer for internal service-to-service calls (/v1/internal/*).
Device JWT	The long-lived (1 year) token a Pi holds after pairing.
Reactive vs proactive	Reactive = the agent responds to an incoming message. Proactive = the agent starts the conversation (a cron firing, a send_message).
Room	A LiveKit room, named room_<user_id>. The Pi and voice-bridge join the same one.

Other names you'll see

Term	What it is
The pivot	The big refactor that moved us to Supabase + LiveKit + upstream hermes. Several old components (sudo-relay, a forked agent, a Playwright sidecar) were deleted. If a doc mentions those, it predates the pivot.
reSpeaker / XVF3800	A mic-array board used on some Pis. Ships in the wrong mode and must be flashed once.
SoftAP	The temporary WiFi access point the Pi broadcasts during first-time setup so you can give it your home WiFi password.
Wake word	"hey sudo" — the phrase that wakes the device. Detected on-device by a small ONNX model.