Repository navigation
Setup
End-to-end installation, from a fresh Hermes server to a working voice conversation. Target: under five minutes from clone to first "hi Hermes".
Server (Linux):
-
python3≥ 3.10 with thevenvmodule (apt install python3-venvon Debian / Ubuntu — the installer offers to do this for you if it's missing). -
systemd(every mainstream distro from the last decade). - The Hermes agent reachable on a local HTTP port (default
http://localhost:8642— see Hermes API server docs). - Root, or a user with
sudo.
Desktop (macOS — only fully-tested platform today):
- macOS 12 (Monterey) or newer for the Apple Silicon build; Intel works too but is built separately.
- Node.js ≥ 22 only required if you build from source. A pre-built
.dmgis published per release. - For wake-word activation:
python3≥ 3.10 withopenwakewordandsounddevice(the runner ships these inresources/python/requirements.txt). - For local Whisper:
whisper-clifrombrew install whisper-cpp— the app auto-detects it on$PATHand downloads the GGML model the first time you press Talk. - For local Piper: nothing — the app creates a Python venv at
~/Library/Application Support/Voice Gateway/piper/venvandpip install piper-ttson first use.
For the gory details on how each of these is discovered or installed, see Speech-To-Text and Text-To-Speech.
curl -fsSL https://raw.githubusercontent.com/VivaldiCode/voice-gateway/main/server/install.sh | bashThe script:
- Re-execs itself under
sudo(via a temp-file dance — see Hermes-Voice-Bridge#install-script for why a naivesudo -E bash $0doesn't work for piped installs). - Auto-installs
curl,git,python3, andpython3-venvif any are missing, prompting once per package via the host's package manager (apt,dnf,pacman, etc). - Prompts for:
-
Bridge port (default
8765). -
Hermes API URL (default
http://localhost:8642). - Hermes API key — paste the bearer token your Hermes instance issues. Press Enter to skip if Hermes is unauthenticated.
-
Bridge port (default
- Creates a system user
hermes-voice(no shell), drops a Python virtualenv at/opt/hermes-voice-bridge/venv, generates a 32-byte pairing token, writes/etc/hermes-voice-bridge/config.toml(mode0640,root:hermes-voice), and enables asystemdunithermes-voice-bridge.service. - Prints a banner with the pairing token and bridge URL.
The script is idempotent: re-running upgrades the Python package,
preserves the pairing token, and preserves the Hermes API key. Pass
--yes for unattended installs, --port / --hermes-url /
--hermes-api-key to skip individual prompts, or set the matching
BRIDGE_PORT / HERMES_URL / HERMES_API_KEY env vars.
# Unattended install for CI / packer:
HERMES_API_KEY=sk-... ASSUME_YES=1 \
curl -fsSL https://raw.githubusercontent.com/VivaldiCode/voice-gateway/main/server/install.sh | sudo -E bashsystemctl status hermes-voice-bridge
journalctl -fu hermes-voice-bridge
curl http://localhost:8765/healthz # → {"ok": true, "version": "0.1.0"}The expected log line on every successful turn:
hermes responded 200 (Content-Type=text/event-stream)
hermes stream done — N delta(s), M chars total
See Troubleshooting for what each variant means.
The bridge POSTs to ${hermes_base_url}/v1/chat/completions in the
OpenAI Chat Completions format. If your Hermes is shaped differently,
edit
/opt/hermes-voice-bridge/src/hermes_voice_bridge/hermes_adapter.py,
restart with sudo systemctl restart hermes-voice-bridge. Keep the
async def stream_chat(...) signature — everything else is yours to
change. See Hermes-Voice-Bridge#hermesadapter for the contract.
Easy path — grab the latest pre-built DMG from releases.
Build from source:
git clone https://github.com/VivaldiCode/voice-gateway
cd voice-gateway
npm install
npm run build:mac # writes release/*.dmg
open release/*.dmgThe build pipeline runs an afterPack hook that injects
NSMicrophoneUsageDescription into every helper Info.plist and
ad-hoc-signs the bundle with the hardened runtime. See
Build-And-Packaging for why all of that is necessary on
unsigned builds.
Opening the freshly-installed app drops you into the first-run pairing wizard:
flowchart LR
A[Launch app] --> B{Pairing<br>saved?}
B -- no --> W1[Wizard step 1<br>Bridge URL]
W1 --> W2[Wizard step 2<br>Paste token + test]
W2 --> W3[Wizard step 3<br>Pick activation mode]
W3 --> Done[Save settings<br>open main UI]
B -- yes --> Done
-
Where is your Hermes? Paste the bridge URL printed by
install.sh. The wizard validates the protocol prefix locally (ws://orwss://). -
Paste the pairing token. Click Test connection — the renderer
asks the main process to open a WebSocket, send
hello, and confirm it getswelcomeback. The button only lights green when that roundtrip succeeds. Bad tokens map to a friendly "the token wasn't accepted" message (seetestPairingfor the full error mapping). -
How do you want to talk? Two cards:
-
Push-to-talk button (recommended) — the mic only opens while
you hold the on-screen button or press the global hotkey (default
Cmd+Shift+H/Ctrl+Shift+H). - Always listening (wake word) — passive listening using openWakeWord. Pick a wake word from the list.
-
Push-to-talk button (recommended) — the mic only opens while
you hold the on-screen button or press the global hotkey (default
Click Done! → Open Voice Gateway.
Hold the round purple button (or press the hotkey), speak, release. The State-Machine cycles:
IDLE → CAPTURING → STREAMING → THINKING → SPEAKING → IDLE
(green) (yellow) (yellow) (purple)
The transcript view shows your words and the assistant's reply as they arrive. While the assistant is talking you can barge in — pressing the button again immediately cancels playback and opens the mic for a new turn.
The Definições window (separate BrowserWindow opened by the gear
icon) has six tabs:
| Tab | What it controls |
|---|---|
| Voz | TTS provider (Piper / ElevenLabs), voice picker, voice-test textarea (type any phrase to hear it spoken) |
| Microfone | Input device picker, macOS permission diagnostic, live VU meter |
| Reconhecimento | STT provider, Whisper model size, language, OpenAI key |
| Ativação | PTT vs wake word, hotkey, minimum audio length (filters accidental taps before they hit STT) |
| Conexão | Re-pair with a different bridge |
| Avançado | Factory reset |
Full reference: Renderer-UI#settingspanel.
Wake-word runs the Python script at
resources/python/wake_word_runner.py
as a child process. The script opens the microphone itself via
sounddevice, runs openwakeword over 80 ms 16 kHz frames, and writes
JSON lines to stdout. See Wake-Word-Detection for the deep dive.
If the Voice Gateway icon in the system tray turns green, the detector is alive. If you see "Could not start the detector", install the runner's dependencies manually:
python3 -m pip install -r resources/python/requirements.txtChanging STT provider (Whisper local ↔ OpenAI), TTS provider (Piper ↔ ElevenLabs), or the pairing triggers a live rebuild of the Conversation-Orchestrator in the main process:
sequenceDiagram
participant UI as Settings UI<br>(renderer)
participant IPC
participant Store as electron-store
participant Main as main process
participant Orch as Orchestrator
UI->>IPC: vg.settings.set({stt:{provider:'openai_whisper',...}})
IPC->>Store: merge & persist
Store-->>Main: onChange(next)
Note over Main: snapshot differs<br>(stt / tts / pairing)
Main->>Orch: dispose old<br>build new<br>prepareStt() + prepareTts()
Orch-->>UI: TTS_STATUS + STT_STATUS broadcast<br>(to ALL windows)
This is implemented in
src/main/index.ts
under settings.onChange(...). See Conversation-Orchestrator#lifecycle.
- Curious why a turn sometimes ends in silence? → Troubleshooting
- Want to add an STT/TTS provider? → Speech-To-Text / Text-To-Speech
- Want to extend the protocol with a new event? → Protocol
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