Docker/BuildKit enforces lowercase org names in registry paths. Gitea's Org1 (mixed-case) is accepted by the Gitea API but rejected by BuildKit as 'repository name must be lowercase'. Switching to hermes/ namespace, which is lowercase and where the runner's REGISTRY_TOKEN has push rights.
hermes-voice-gateway
Local voice realtime bridge: browser ↔ voice-gateway (WebSocket+PCM) ↔ hermes-proxy (OpenAI-compatible) ↔ Hermes (minimax API).
Architecture
[Browser] [voice-gateway] [hermes-proxy] [Hermes]
mic/speaker ⇄ WS+PCM on :8765 ⇄ POST /v1/chat ⇄ minimax API
│
├─ STT: faster-whisper base (VAD-filtered)
└─ TTS: piper ru_RU-denis-medium
Half-duplex by design: client sends PCM chunks, server flushes STT on silence, calls LLM with streaming, splits reply into sentences, sends each sentence to TTS, streams PCM back.
Build & release
Image is built by Gitea Actions on every semver tag push (.gitea/workflows/release.yml):
git tag v0.1.0
git push origin v0.1.0
# → gitea.rudolf.keenetic.link/Org1/hermes-voice-gateway:v0.1.0 + :latest
Pushed to Gitea Packages (built-in container registry), not a separate Docker registry. Brencher pulls by semver tag from the same endpoint; the gitea.rudolf.keenetic.link hostname resolves inside the cluster.
Required secrets on the repo (Settings → Actions → Secrets):
REGISTRY_USERNAME— Gitea user with push rights to thehermesnamespace in Packages (Docker/BuildKit enforces lowercase org names in registry paths;Org1is mixed-case and Docker rejects it asrepository name must be lowercase).REGISTRY_TOKEN— that user's API token.
Stack layout
gateway/server.py— aiohttp app, WS endpoint + HTTP staticgateway/pipeline.py— STT / LLM / TTS adapter classesgateway/config.py— env-driven configgateway/static/{index.html,app.js,styles.css}— browser clientDockerfile— image build on top ofnousresearch/hermes-agent:v2026.8.3compose.yaml— Swarm stack with placement onrudolf-T.gitea/workflows/release.yml— tag-triggered image release
Required env (compose)
| Var | Default | Notes |
|---|---|---|
version |
injected by brencher | semver tag of the image to deploy |
HERMES_PROXY_TOKEN |
empty | Bearer if hermes-proxy requires one |
Voice-gateway runtime env (already in compose): HERMES_PROXY_URL, PIPER_VOICE_PATH, LLM_MODEL, SAMPLE_RATE_IN, SAMPLE_RATE_OUT, MAX_SESSION_SECONDS, MAX_SILENCE_MS.
Wire protocol
Client → server (WS):
- binary frame: PCM Int16 mono at
SAMPLE_RATE_IN - text JSON
{"type": "flush"}— force STT on partial audio - text JSON
{"type": "reset"}— clear conversation history - text JSON
{"type": "ping"}— keep-alive
Server → client (WS):
- binary frame: PCM Int16 mono at
SAMPLE_RATE_OUT - text JSON
{"type": "ready"}— handshake complete - text JSON
{"type": "transcript", "text": "..."} - text JSON
{"type": "reply", "text": "..."}— full assistant text after TTS finishes - text JSON
{"type": "error", "message": "..."}
Dependencies
nousresearch/hermes-agent:v2026.8.3— base image.faster-whisper— STT, modelbaseint8 quantized, downloaded on first use.piper-tts+onnxruntime— TTS, voice model must be mounted atPIPER_VOICE_PATH.aiohttp— HTTP/WS server.gitea.rudolf.keenetic.link— Gitea Packages registry, push target. Image published under thehermesnamespace (lowercase, OCI-compliant).
The voice-gateway expects hermes-proxy reachable at http://hermes-proxy:8645 on the same hermes_proxy overlay.