Repository navigation
Releases
v0.2.9
What's Changed
- fix(stt): pass -bs 5 -bo 5 to whisper-cli for better accuracy (closes #110 subset) by @VivaldiCode in #111
Full Changelog: v0.2.8...v0.2.9
v0.2.7
What's Changed
- chore(ci): drop mac-x64 from release matrix (closes #66, future re-add in #85) by @VivaldiCode in #86
Full Changelog: v0.2.6...v0.2.7
Voice Gateway 0.2.0 — multi-platform (5 of 6 binaries; mac-x64 deferred to #66)
Multi-platform release. Voice Gateway is now distributed for macOS, Windows, and Linux as installable binaries — Apple Silicon, Intel-Windows, ARM-Windows, x86_64-Linux, ARM-Linux. The macOS Intel (x64) binary is missing from this release because GitHub's macos-13 runner queue stalled at workflow time; tracked in issue #66.
What's new since v0.1.0
- 🆕 Multi-platform release pipeline — the new
release.ymlworkflow runs a 6-way matrix (mac arm64/x64 + win arm64/x64 + linux arm64/x64) on tag push and ships everything through a single GitHub Release. Seedocs/Build-And-Packaging.md. (PR #53) - 🛡 Build doctor pre-flight — catches a corrupted-
node_modulesfailure mode that's specific to external/exFAT-ish dev volumes. Surfaces a recovery command before the build wastes 6 s on a doomed run. (PR #49, issue #48) - ⚙️ Branch protection enforcement everywhere — pipeline V2 is now mandatory: issue → branch → PR → sub-agent review → CI green → squash-merge → tag → multi-platform release.
enforce_admins: true. (Internal pipeline work; tracked in issues #50, #52, #54, #65.) - 🤖 First card from the GitHub Project board — sub-issue decomposition + single PR pattern landed in CONTRIBUTING + framework wiki. (Issue #55, in-flight as PR #64.)
- 🔧 Tooling upgrades — Dependabot grouped patches:
actions/setup-python5→6,actions/configure-pages5→6,actions/upload-pages-artifact3→5,actions/checkout4→6,actions/upload-artifact4→7,electron-storepatch,electron-logpatch,lucide-reactpatch.
Install
Pick the build for your platform:
| Platform | Asset |
|---|---|
| macOS (Apple Silicon, M-series) | Voice Gateway-0.2.0-arm64.dmg |
| Windows (x64) | Voice Gateway Setup 0.2.0-x64.exe |
| Windows (ARM64) | Voice Gateway Setup 0.2.0-arm64.exe |
| Linux (x86_64) | Voice Gateway-0.2.0-x86_64.AppImage |
| Linux (ARM64) | Voice Gateway-0.2.0-aarch64.AppImage |
| macOS (Intel x64) | not in this release — see #66 |
After install:
- macOS: DMGs are ad-hoc signed. First launch needs the Gatekeeper override (Right-click → Open → Open the warning dialog).
- Windows: EXEs are unsigned (no Authenticode cert). SmartScreen will warn on first install; click "More info → Run anyway".
- Linux:
chmod +xthe AppImage if your file manager didn't do it.
Run the pairing wizard with your Hermes bridge URL + token. Pre-flight check in the wizard verifies the bridge before continuing.
SHA-256 checksums
e83cdd4dc324e6513dc755961d69b316247df80182d338eb6c8a1bbcc7795a62 Voice Gateway Setup 0.2.0-arm64.exe
335dca4ca71454ff8f8d540adc701b07a369d7374478acc50b6a0266936ff6b2 Voice Gateway Setup 0.2.0-x64.exe
bc3f59b00f1a8f6b4809a643e5daa2ba7381f138ab8f974b3d8dabfa0acaf41f Voice Gateway-0.2.0-aarch64.AppImage
652115cef0fbb67f1fd15c7ec3d0d02b7a0c90d5ca585ef9a8b8c37a93ecdf12 Voice Gateway-0.2.0-arm64.dmg
cc3b61efcb5726a9b63b4c269881415e324e8458c49ea109d05225d19b890fd9 Voice Gateway-0.2.0-x86_64.AppImage
Known limitations
- macOS Intel (x64) DMG missing from this release. The
macos-13runner queue stalled at workflow time (1h14m queued, never started). Issue #66 tracks the fix — likely switch to building mac-x64 frommacos-latestvia cross-compile or drop the target until Apple stops shipping Intel-supported macOS. - No Apple Developer ID signing → DMG triggers Gatekeeper on first launch.
- No Authenticode signing on the Windows EXEs → SmartScreen warning on first install.
- AppImage on Linux is unsigned; users can verify the SHA-256 above.
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
- #55 — multi-LLM integration (Claude / Ollama / Grok / ChatGPT) — in flight as PR #64 with sub-issues #56–#63
- #54 — V2 pipeline enforcement (auto-tag + Kanban hook)
- #66 — mac-x64 build fix
Thanks for trying it. Bug reports + feature requests welcome via Issues.
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