hermes 0dc91dfe4a
release / build (push) Failing after 41s
fix(ci): publish image under lowercase hermes namespace
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.
2026-09-13 14:10:36 +00:00

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 the hermes namespace in Packages (Docker/BuildKit enforces lowercase org names in registry paths; Org1 is mixed-case and Docker rejects it as repository name must be lowercase).
  • REGISTRY_TOKEN — that user's API token.

Stack layout

  • gateway/server.py — aiohttp app, WS endpoint + HTTP static
  • gateway/pipeline.py — STT / LLM / TTS adapter classes
  • gateway/config.py — env-driven config
  • gateway/static/{index.html,app.js,styles.css} — browser client
  • Dockerfile — image build on top of nousresearch/hermes-agent:v2026.8.3
  • compose.yaml — Swarm stack with placement on rudolf-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, model base int8 quantized, downloaded on first use.
  • piper-tts + onnxruntime — TTS, voice model must be mounted at PIPER_VOICE_PATH.
  • aiohttp — HTTP/WS server.
  • gitea.rudolf.keenetic.link — Gitea Packages registry, push target. Image published under the hermes namespace (lowercase, OCI-compliant).

The voice-gateway expects hermes-proxy reachable at http://hermes-proxy:8645 on the same hermes_proxy overlay.

S
Description
No description provided
Readme
60 KiB
Languages
Python 56.9%
JavaScript 30.8%
CSS 6.7%
HTML 4.2%
Dockerfile 1.4%