Repository navigation
Voice Gateway 0.1.0 — first release
First public release of Voice Gateway — a local-first desktop voice client for the Hermes agent. Push-to-talk or wake-word in, streaming text + speech out, with your choice of STT/TTS backends and no telemetry.
What's in this release
Core voice loop
- Push-to-talk with a configurable global hotkey (default
Cmd+Shift+Hon macOS,Ctrl+Shift+Helsewhere) - Wake-word activation powered by openWakeWord — bundled "Hey Jarvis" model plus custom-phrase training via the Settings UI
- Cancel mid-utterance — Escape or the visible cancel button stops capture and returns to IDLE
- Barge-in — speaking over the bot interrupts TTS and starts a new turn
Conversation surface
- Live transcript pane with user/assistant alternation, copy-to-clipboard, turn counter, export to file (
Cmd+S), clear (Cmd+L), and persistence of the last 20 turns across restarts - State orb in the header reflects the FSM state (IDLE / CAPTURING / THINKING / SPEAKING / ERROR)
- Minimalist mic + speaker pickers in the main header for quick device switching
- Connection indicator with retry counter; click to reconnect immediately
- Error toast with "Copy diagnostic" button, "Try again" action, auto-dismiss after 4 s
- Tray menu with Show window / Open Settings / Quit
STT (speech-to-text) backends
- Whisper local via whisper.cpp — auto-detects the
whisper-clibinary on PATH, auto-downloadsggml-base.binfrom Hugging Face on first use - OpenAI Whisper API — bring your own key
- 30 s default transcription timeout (configurable)
- Live-swap STT providers without restart
TTS (text-to-speech) backends
- Piper local — auto-creates a Python venv on first use and pulls the piper-tts wheel
- ElevenLabs API — bring your own key
- 30 s / 60 s default synthesis timeouts (configurable)
- Voice mute toggle in the header
Pairing & settings
- Pairing wizard with 3 steps + back/cancel/step indicator, URL history (last 3), draft persistence, server-version probe, masked token field with whitespace-trim on paste
- Five-tab Settings panel: Connection · Recognition · Voice · Activation · Advanced
- Live updates — changing a setting in Settings reaches the orchestrator without a restart
- Settings persistence + factory reset button in Advanced
- Auto-launch on login toggle
- Live log preview for debugging from inside Settings
Bridge / server side
- Companion Python service at
server/hermes-voice-bridge(aiohttp WebSocket bridge to a Hermes agent) - One-line
install.shfor systemd setup - HTTP
/healthz+ bridge/wsendpoint - WebSocket reconnect with bounded exponential backoff (~16 s cap)
- Auto-reconnect on window focus
macOS specifics
- Apple Silicon arm64 DMG
- Hardened runtime + ad-hoc codesign in
afterPack— keeps the bundle's Designated Requirement stable across rebuilds so the user's microphone permission grant survives an update NSMicrophoneUsageDescriptioninjected into the helper bundles sogetUserMediaactually surfaces a prompt- Resource-fork cleanup in the bundle (defends against
._*AppleDouble files breaking codesign)
Quality
- Branch protection on
mainwith required status checks (lint+typecheck, vitest matrix Node 20/22, Playwright E2E, Pytest, CodeQL) andenforce_admins: true - CodeQL scans on every PR + weekly
- Dependabot weekly grouped updates for npm, pip, github-actions
- SHA-pinned GitHub Actions
SECURITY.mdwith disclosure policy- Build doctor pre-flight (
tools/build-doctor.cjs) — catches a corrupted-node_modulesfailure mode beforeelectron-vite buildwastes 6 s on a doomed run - vitest unit suite (incl. settings-store v1→v2 migration test, state-machine coverage, protocol fuzz, timeout helpers)
- Playwright E2E suite covering: pairing, multi-turn, cancel, barge-in, reconnect, factory reset, hotkey rebind, settings live-update, output-device live-switch, backpressure under many audio chunks, capability negotiation, wake-word validation, and ~20 more
- Pytest suite for the Python bridge + wake-word runner
Documentation
- Full GitHub Wiki auto-synced from
docs/on every merge tomain - Pages: Home, Architecture, Audio Pipeline, Build & Packaging, Conversation Orchestrator, Development Guide, Glossary, Hermes Voice Bridge, IPC Layer, Protocol, Renderer UI, Settings & Storage, Setup, Speech-To-Text, State Machine, Testing Guide, Text-To-Speech, Troubleshooting
- GitHub Pages landing page
Install
- Download
Voice Gateway-0.1.0-arm64.dmgfrom this release - Open the DMG, drag Voice Gateway.app to Applications
- The DMG is ad-hoc signed (no Apple Developer ID). First launch needs the Gatekeeper override: right-click the app in Finder → Open → confirm
- Grant microphone permission when prompted (System Settings → Privacy → Microphone)
- Run the pairing wizard with your Hermes bridge URL + token
See docs/Setup.md for a fuller walkthrough.
Known limitations
- macOS arm64 only in this release. Linux AppImage and Windows NSIS builds work from source (
npm run build:linux/:win) but aren't published here yet — see issue #46 (React 19) and #45 (Vite 8 / Electron 39) for the upcoming coordinated upgrade work that will unlock the CI matrix. - No Apple Developer ID — the DMG is ad-hoc signed. Right-click → Open the first time.
- Piper local TTS resources aren't bundled in the DMG. The app auto-installs them into
<userData>/piper/venvon first Piper use, which needs Python 3.10+ on PATH. ElevenLabs works out of the box with an API key. - Whisper local STT binary isn't bundled either —
brew install whisper-cppor followdocs/Troubleshooting.mdto point at a custom build. OpenAI Whisper API works out of the box with a key.
Verify the download
shasum -a 256 "Voice Gateway-0.1.0-arm64.dmg"
# Expected: cdb327dc5289a391679f0777cf0bf3aa2f97a5cc3c849d3ad00ba1a691ffa6b4
(If the upstream CI build replaces this asset, the SHA will differ — re-check against this release's checksum file once the workflow finishes.)
What's next
Tracked in open issues:
- #45 — coordinated upgrade: Vite 8 + Electron 39 +
@vitejs/plugin-react6 - #46 — React 19 migration
- #47 — Dependabot config: skip majors on locked packages until #45 / #46 land
- #48 — closed by the build-doctor change shipped in this release
Thanks for trying it. Bug reports + feature requests welcome via Issues.
— The Voice Gateway team