Repository navigation
Hermes Voice Bridge
The bridge is a tiny Python aiohttp WebSocket server that lives on the same host as the Hermes agent and acts as a protocol adapter:
- Speaks the Protocol to desktop clients.
- Speaks the OpenAI Chat Completions HTTP API to Hermes.
Why have it at all? Two reasons:
- Auth boundary. Hermes' own API might be unauthenticated, or secured by a long-lived API key we don't want to ship to every desktop client. The bridge holds the Hermes key server-side and authenticates clients with a separate pairing token.
- Streaming bridge. The desktop talks chunks-and-events over a WebSocket; Hermes streams Server-Sent Events. Converting between the two is exactly what aiohttp's request handlers are good at.
Source:
server/hermes-voice-bridge/.
| File | Purpose |
|---|---|
__main__.py |
python -m hermes_voice_bridge entrypoint → server.run()
|
server.py |
aiohttp app, /ws and /healthz routes, per-turn dispatch |
auth.py |
Bearer token extraction + constant-time comparison |
config.py |
TOML loader for /etc/hermes-voice-bridge/config.toml
|
hermes_adapter.py |
OpenAI chat-completions client with streaming + non-stream fallback |
The whole thing is ~600 lines including comments.
sequenceDiagram
participant C as Desktop client
participant B as Bridge
participant H as Hermes API
C->>B: WS upgrade (Authorization: Bearer <token>)
Note over B: auth middleware<br>extract_bearer + compare_digest
B-->>C: 101 Switching Protocols
C->>B: hello
B-->>C: welcome { session_id, capabilities: ['streaming_text'] }
C->>B: start_turn { turn_id }
C->>B: transcript { turn_id, text, final: true }
C->>B: end_turn { turn_id }
Note over B: asyncio.create_task(_run_turn)
B-->>C: thinking { turn_id }
B->>H: POST /v1/chat/completions<br>{stream: true}<br>messages = [history..., user]
H-->>B: data: {...delta...}\n\n
B-->>C: response_text { delta, final: false }
H-->>B: data: [DONE]
B-->>C: response_text { full, final: true }
B-->>C: response_end { turn_id }
The _auth_middleware runs on every request to /ws:
async def _auth_middleware(request, handler):
if request.path != "/ws":
return await handler(request)
token = extract_bearer(request.headers.get("Authorization"))
if not is_valid_token(config.token, token):
return web.Response(status=401, text="unauthorized")
return await handler(request)is_valid_token uses hmac.compare_digest so an attacker can't time
the comparison to recover the token byte-by-byte.
/healthz is intentionally unauthenticated — it's used by
systemd/uptime probes and returns {ok: true, version}.
The adapter keeps a per-session deque of {role, content} messages so
multi-turn conversations work without the desktop having to resend
context every turn:
class HermesAdapter:
def __init__(self, ..., history_turns=16):
self._history: Dict[str, Deque[Dict[str, str]]] = {}
self._history_max = max(2, history_turns)
def _record(self, session_id, role, content):
d = self._history.setdefault(session_id, deque(maxlen=self._history_max))
d.append({"role": role, "content": content})session_id is the WS connection id minted in
ws_handler (secrets.token_hex(8)). When the socket closes, we drop
the history:
finally:
forget = getattr(adapter, "forget", None)
if callable(forget):
forget(session_id)This means a reconnect starts fresh — by design. Persistent multi-day memory is the Hermes agent's job (RAG, vector store, etc), not the bridge's.
async def stream_chat(self, *, text, session_id) -> AsyncIterator[str]:
messages = self._session_messages(session_id)
messages.append({"role": "user", "content": text})
payload = {"model": self._model, "messages": messages, "stream": True}
delta_count = 0
async with self._session() as session:
async with session.post(url, json=payload, headers=headers) as resp:
if resp.status == 401: raise HermesUpstreamError(...)
async for delta in _iter_sse_deltas(resp):
if delta:
delta_count += 1
yield delta
if delta_count == 0:
# Some Hermes builds and proxies ignore stream=true.
# Retry with stream=false and yield the whole body as one delta.
fallback = await self._fetch_non_stream(text=text, headers=headers, messages=messages)
if fallback:
yield fallbackThe fallback handles two real-world bugs:
- Some Hermes builds parse
stream=truebut always reply with one final JSON body (no SSE). - Some HTTP proxies (Nginx without
proxy_buffering off) accumulate the SSE stream into one chunk that arrives all-at-once with nodata:line breaks.
The fallback path silently retries with stream: false, parses the
OpenAI shape (choices[0].message.content), and yields the whole text
as a single delta. The desktop client sees an identical
response_text final=true → response_end sequence either way.
async def _iter_sse_deltas(resp) -> AsyncIterator[str]:
buffer = b""
async for chunk in resp.content.iter_any():
buffer += chunk
while b"\n" in buffer:
raw_line, buffer = buffer.split(b"\n", 1)
line = raw_line.decode("utf-8", errors="replace").rstrip("\r").strip()
if not line: continue
if line.startswith("data:"): line = line[5:].strip()
if line in ("", "[DONE]"): continue
yielded = _extract_delta(line)
if yielded: yield yielded
# Flush tail (some servers omit the trailing newline).
...The previous implementation just iterated resp.content and split each
TCP chunk on \n directly. That broke when a data: {...}\n\n event
straddled two chunks — the JSON parser would see two half-objects and
silently drop both. The buffered version is robust to arbitrary chunk
boundaries.
_extract_delta handles three shapes:
| Server shape | Parsed as |
|---|---|
{"choices":[{"delta":{"content":"X"}}]} |
OpenAI streaming |
{"choices":[{"message":{"content":"X"}}]} |
OpenAI non-streaming |
{"text":"X"} / {"delta":"X"} / {"content":"X"}
|
Tolerant fallbacks |
| Raw text (no JSON) | Treated as the delta |
So the bridge survives a surprising range of "OpenAI-compatible" APIs.
/etc/hermes-voice-bridge/config.toml is generated by install.sh
with mode 0640 and owner root:hermes-voice:
[bridge]
host = "0.0.0.0"
port = 8765
token = "<base64url 32-byte secret>"
[hermes]
base_url = "http://localhost:8642"
request_timeout = 30
api_key = "" # Bearer for Hermes' own API, if it requires oneThe path can be overridden via HERMES_VOICE_BRIDGE_CONFIG for tests
and dev environments.
server/install.sh
is the one-liner installer:
curl -fsSL https://raw.githubusercontent.com/VivaldiCode/voice-gateway/main/server/install.sh | bashWhat it does, in order:
-
Re-exec under sudo via a temp-file dance:
The naive
if [ "$EUID" -ne 0 ]; then tmp=$(mktemp) cat > "$tmp" <<< "$(cat "$0")" # or curl re-fetch exec sudo bash "$tmp" "$@" fi
sudo -E bash "$0"doesn't work when$0is/dev/fd/63(a bash process substitution fromcurl … | bash). -
Detect package manager (
apt,dnf,pacman,apk,zypper) and offer to install any ofcurl,git,python3,python3-venvthat's missing. Prompts once per package;--yes/ASSUME_YES=1skips the prompt. -
Prompt for bridge port (8765), Hermes URL (8642), and Hermes API
key. Flags / env vars skip individual prompts:
--port/BRIDGE_PORT,--hermes-url/HERMES_URL,--hermes-api-key/HERMES_API_KEY. -
Create system user
hermes-voice(no shell, no home). -
Create venv at
/opt/hermes-voice-bridge/venv, install the package from the repo'sserver/hermes-voice-bridgedirectory. -
Generate a
secrets.token_urlsafe(32)pairing token (or reuse existing on re-install — the script is idempotent). -
Write
/etc/hermes-voice-bridge/config.toml. -
Write the
systemdunit at/etc/systemd/system/hermes-voice-bridge.service. -
systemctl daemon-reload && systemctl enable --now hermes-voice-bridge. - Print the pairing token + bridge URL in a friendly banner.
The script is idempotent — re-running upgrades the Python package and preserves the token and Hermes API key. Pass any flag to override defaults for unattended installs (CI / packer / Ansible).
[Unit]
Description=Hermes Voice Bridge
After=network.target
[Service]
Type=simple
User=hermes-voice
Group=hermes-voice
ExecStart=/opt/hermes-voice-bridge/venv/bin/python -m hermes_voice_bridge
Restart=on-failure
RestartSec=2
[Install]
WantedBy=multi-user.targetLogs go to journald — journalctl -fu hermes-voice-bridge is the
canonical debug tool. The expected log line per successful turn:
hermes responded 200 (Content-Type=text/event-stream)
hermes stream done — N delta(s), M chars total
If you see "hermes responded 200 (Content-Type=application/json)"
followed by "non-stream fallback OK" — Hermes ignored stream: true
and the fallback kicked in. That's working as intended, just slower
because the user has to wait for the entire response before seeing
text.
If your Hermes API is shaped differently (different path, different
auth, different response format), edit
hermes_adapter.py
and systemctl restart hermes-voice-bridge. Keep the
async def stream_chat(*, text, session_id) -> AsyncIterator[str]
signature so the rest of the bridge keeps working.
The HTTP layer (_session, headers, auth) is yours to change — the
default uses Bearer auth when hermes.api_key is set.
The bridge has a pytest suite at
server/hermes-voice-bridge/tests/
that exercises:
- the
/wsupgrade with valid + invalid tokens, - the welcome handshake,
- a fake
HermesAdapterthat yields chosen deltas, - the non-stream fallback path,
- SSE chunk-boundary edge cases.
Run with pytest -q from inside the venv. The TS-side end-to-end test
(tests/integration/bridge-text-roundtrip.test.ts) hits a real
running bridge — see Testing-Guide.
Voice Gateway — VivaldiCode/voice-gateway. MIT licensed. Wiki sources live under docs/; run ./docs/sync-wiki.sh to publish.
Getting started
Architecture
- Architecture — system overview
- State-Machine — conversation FSM
- Conversation-Orchestrator — main glue
- WebSocket-Client — Hermes connection
- IPC-Layer — main ↔ renderer
- Settings-And-Storage — config persistence
Audio
- Audio-Pipeline — capture & playback
- Speech-To-Text — STT adapters
- Text-To-Speech — TTS adapters
- Wake-Word-Detection — openWakeWord
Server
- Hermes-Voice-Bridge — Python bridge
- Protocol — WebSocket spec
Platform
- Build-And-Packaging — electron-builder
- macOS-Permissions — TCC, signing
- Renderer-UI — React components
Project
- Testing-Guide — unit, integration, E2E
- Development-Guide — contributing
- Glossary — terms