Repository navigation
Build And Packaging
The desktop app is bundled with
electron-builder into a macOS .dmg
(Apple Silicon arm64 target), a Linux AppImage, and a Windows
nsis installer. The default npm run build produces all three when
run on the matching host; CI uses
npm run build:mac / :linux / :win to target one platform.
Config: electron-builder.yml.
Pre-bundle Vite build:
electron.vite.config.ts.
flowchart LR
Doc[build-doctor<br>tools/build-doctor.cjs] --> Vite[electron-vite build]
Src[src/] --> Vite
Vite --> Out[out/main, out/preload, out/renderer]
Out --> EB[electron-builder]
Resources[resources/] --> EB
EB --> Pack[app packed in .app/.exe/.AppImage]
Pack --> Hook[afterPack hook<br>build/after-pack.cjs]
Hook --> Dmg[release/*.dmg]
A ~50 ms Node script runs before every build:mac|linux|win and aborts
the build if any of a small set of node_modules entry points have
disappeared.
The check exists because the repo is sometimes mounted from an external
volume whose filesystem (exFAT, MS-DOS) doesn't preserve POSIX metadata
the way APFS does. Individual files inside node_modules occasionally
go missing without the parent tree being obviously broken — the most
recent victim was
node_modules/builder-util/node_modules/fs-extra/lib/index.js (issue
#48), which made electron-builder explode at startup with
MODULE_NOT_FOUND. Without the doctor the failure surfaces only
after electron-vite build has already run (5–8 s of wasted work) and
the error message points at builder-util internals, which is easy to
misdiagnose.
On failure the doctor prints the exact rm -rf + npm install command
to run; see Troubleshooting#build-fails-fast-with-module_not_found-inside-node_modules
for the full story.
To run it standalone:
npm run build-doctor
VG_BUILD_DOCTOR_VERBOSE=1 npm run build-doctor # confirms which files were checkedThe script is in CommonJS (tools/build-doctor.cjs) so it runs without
any TypeScript pipeline — critical because that pipeline is itself one
of the things being checked.
Three build outputs:
| Bundle | Format | Entry | Why |
|---|---|---|---|
main |
ESM | src/main/index.ts |
Modern Node ESM, top-level await available |
preload |
CJS | src/preload/index.ts |
Electron's sandboxed preload doesn't support ESM yet |
renderer |
ESM | src/renderer/main.tsx |
React 18 + Vite HMR in dev |
The preload-as-CJS rule is a recurring bite point — see
electron/electron #28981.
Vite is told format: 'cjs', extension: '.cjs' for that bundle so the
main process can require() the absolute path
join(__dirname, '../preload/index.cjs').
The dev server:
npm run dev # electron-vite dev — HMR on the renderer, restart on main changesThe dev server only handles the renderer; the main process is just re-spawned on every TypeScript change.
extraResources:
- from: resources/python → to: python # wake_word_runner.py + requirements.txt
- from: resources/piper → to: piper # (currently empty; voices live in userData)
- from: resources/scripts → to: scripts # any one-off shell helpers
- from: resources/icon.png → to: icon.png # used by Tray + window icon
- from: resources/icon.svg → to: icon.svg
- from: resources/icons → to: icons # icon-16/32/64/...pngThese end up in Contents/Resources/ on macOS and
resources/ on Linux/Windows. The main process picks them up via
process.resourcesPath — see
src/main/asset-paths.ts.
We don't have an Apple Developer ID. The build is ad-hoc-signed
instead — codesign --sign - — which is enough for the OS to remember
TCC permission grants across rebuilds.
The trick is that electron-builder's identity: false config doesn't
actually run codesign itself. It hands you a bundle whose binaries
are only "linker-signed" with a stale Identifier=Electron. macOS TCC
binds permissions to the
Designated Requirement
of the bundle, so a fresh "Electron" identifier every rebuild means
every rebuild looks like a different app and the user's microphone
grant evaporates.
The
afterPack hook
fixes this:
execSync(
`codesign --force --deep --options runtime --timestamp=none ` +
`--entitlements build/entitlements.mac.plist --sign - "${appPath}"`,
);| Flag | Why |
|---|---|
--force |
Replace existing (linker-only) signatures |
--deep |
Walk into Frameworks/ and resign every helper |
--options runtime |
Turn on the hardened runtime (otherwise entitlements ignored) |
--timestamp=none |
Skip Apple's TSA — we don't need notarization |
--entitlements … |
Inject audio-input, allow-jit, disable-library-validation
|
--sign - |
Ad-hoc identity (no Developer ID needed) |
After signing, the hook also runs codesign -dv to print the resulting
signature info into the build log — useful when chasing "why is macOS
asking for permission again?" issues.
macOS checks NSMicrophoneUsageDescription on the helper bundle's
Info.plist, not just the main app's. electron-builder copies prebuilt
helper bundles verbatim from the Electron release tarball — they ship
with empty plists. Without the key, getUserMedia({audio:true}) hangs
forever or rejects with AbortError even though the user clicked
Allow on the main app's prompt.
The same afterPack hook injects the key into every helper:
for (const helper of fs.readdirSync(frameworksDir).filter(e => e.endsWith('.app'))) {
const plistPath = path.join(frameworksDir, helper, 'Contents', 'Info.plist');
if (!fs.existsSync(plistPath)) continue;
execFileSync('plutil', ['-insert', 'NSMicrophoneUsageDescription', '-string', MIC_DESC, plistPath]);
}See macOS-Permissions for the full rationale.
<key>com.apple.security.device.audio-input</key> <!-- mic permission -->
<key>com.apple.security.cs.allow-jit</key> <!-- V8 JIT -->
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<key>com.apple.security.cs.disable-library-validation</key> <!-- spawn whisper, piper, python -->The last two are essential because we spawn external binaries
(whisper-cli, piper, python3). With hardened-runtime library
validation enabled, those child processes inherit our restrictions
and refuse to load anything not signed by us — which is fine for
Apple binaries but breaks Homebrew's whisper-cli the moment it tries
to load libomp.dylib.
The repo is sometimes mounted from an exFAT external disk, which
sprinkles ._* AppleDouble files alongside every real file. They get
copied into the bundle and break codesign with "Operation not
permitted". The hook does a defensive cleanup:
execFileSync('find', [appPath, '-name', '._*', '-delete'], { stdio: 'pipe' });Linux:
linux:
target: [AppImage]
category: AudioVideo
icon: resources/icon.pngAppImage builds are unsigned and require no Apple-equivalent ceremony.
Windows:
win:
target: [{ target: nsis, arch: [x64] }]
nsis:
oneClick: false
perMachine: false
allowToChangeInstallationDirectory: trueNeither is regularly exercised by maintainers today — macOS is the primary target.
asar: falseWe disable asar so the on-disk layout under Contents/Resources/app/
is greppable. With ~50 MB of compiled output the size cost is
negligible.
PR validation runs in
.github/workflows/ci.yml
(lint + typecheck + vitest matrix + Playwright + Pytest + CodeQL).
DMG / EXE / AppImage release runs in a separate workflow,
.github/workflows/release.yml,
that fires on v* tag pushes (and on manual workflow_dispatch for
ad-hoc testing). The split keeps PR runs cheap — six full installer
builds is slow and only needed when shipping.
Five binaries, one per (platform, arch) pair, five parallel jobs:
| Platform | Arch | Runner | Artifact |
|---|---|---|---|
| macOS | arm64 | macos-latest |
Voice Gateway-<v>-arm64.dmg |
| Windows | x64 | windows-latest |
Voice Gateway Setup <v>.exe |
| Windows | arm64 | windows-latest |
Voice Gateway Setup <v>-arm64.exe |
| Linux | x64 | ubuntu-latest |
Voice Gateway-<v>.AppImage |
| Linux | arm64 | ubuntu-latest |
Voice Gateway-<v>-arm64.AppImage |
macOS Intel (x64) is intentionally not built. GitHub's macos-13
hosted-runner queue is unbounded in practice (we observed 1 h + stalls
on every release tag we tried). Dropping it keeps the matrix completable
within a predictable window. Apple has shipped Apple-Silicon-only Macs
since 2023, so the dropped user base is shrinking organically. Re-add
criteria documented in issue #85; the dropped state was filed under
issue #66.
Windows arm64 and Linux arm64 cross-build cleanly from x64 hosts because their installer payloads are the per-arch electron binary (downloaded by electron-builder) plus our pure-JS bundle.
flowchart LR
Merge[PR squash-merged<br/>into main] --> AT[auto-tag.yml<br/>computes next semver]
AT --> Tag[v0.X.Y pushed]
Tag --> Sync[release.yml syncs<br/>package.json with tag]
Sync --> Build[6× build matrix<br/>per platform/arch]
Build --> Upload[upload-artifact per job]
Upload --> Pub[release job<br/>downloads all + publishes]
Pub --> Rel[GitHub Release v0.X.Y<br/>6 assets attached]
End-to-end the committer pushes a PR; everything past the squash-merge is automated.
-
PR squash-merged into
main. -
auto-tag.ymlruns on the merge commit, reads the squash-commit subject, computes the next semver:-
feat:/feat(scope):→ minor bump -
feat!:/BREAKING CHANGEin body → major bump - anything else → patch bump
-
[skip-tag]in the commit message → opt out
-
-
v0.X.Ypushed;release.ymlfires on the tag push. -
release.ymlsyncspackage.jsonwith the pushed tag (in-place on the runner, no commit) so the DMG/EXE/AppImage filenames track the actual release version, not the stalepackage.jsonvalue. - The build matrix runs in parallel; each job uploads its artifacts.
- A final
releasejob (only on tag pushes — not onworkflow_dispatch) downloads all six artifacts and publishes them viasoftprops/action-gh-release@v2. Auto-generates release notes unless a manualgh release createalready ran for the same tag (in which case hand-written notes survive and only the assets are updated).
Manual tag push is still supported — useful for cutting an explicit
release (git tag -a v0.X.Y && git push origin v0.X.Y) without
relying on the auto-tag bump rule.
electron-builder is invoked with --publish never in every build
job — without that flag it detects the tag context, decides it should
publish to GitHub Releases itself, looks for GH_TOKEN, fails on the
missing token, and crashes the build before any installer is written.
The framework's rule: exactly one publisher per release —
softprops/action-gh-release@v2. See issue #50 / PR #51 for the
specific failure mode this guards against; the rule lives in this
workflow's header comment too.
For local iteration the build:* npm scripts are enough — they never
try to publish:
npm test
npm run build:mac # macOS arm64 (current host's arch)
npm run build:linux # Linux x64
npm run build:win # Windows x64
ls release/ # → Voice Gateway-<v>-<arch>.dmg/.exe/.AppImageTo build a specific cross-target locally, call electron-builder directly:
npm run build
npx electron-builder --linux --arm64 --publish never| Symptom | Likely cause |
|---|---|
codesign: object file format invalid or unsuitable |
A stray ._* AppleDouble file slipped into the bundle. The hook handles this; if it returns, check that find succeeded. |
Library not loaded: @rpath/Electron Framework |
A helper wasn't re-signed. The hook walks Frameworks/; if you added new helpers, re-check. |
| Renderer blank after install | Vite's renderer outDir doesn't match loadFile path. The pattern is out/renderer/index.html → join(__dirname, '../renderer/index.html'). |
| Microphone permission lost across rebuilds | Ad-hoc signing failed silently; check the [after-pack] codesign output for "main signature: ".
|
hdiutil: create failed - No space left on device |
The default electron-builder DMG path stages its temp file in /private/var/folders/... — i.e. on the system volume. If that volume is low on free space, hdiutil aborts even though the source bundle is small. Workaround: run hdiutil create manually with TMPDIR pointed at a roomier volume (typically the same drive that holds the source tree). The output DMG is identical for the end user; only the staging directory differs. |
MODULE_NOT_FOUND inside node_modules/... immediately after electron-vite build finishes |
A file inside node_modules has disappeared, typically a deeply-nested entry point on external/exFAT volumes. The build-doctor pre-flight should now catch this before electron-vite build runs; if you see this after the doctor passed, add the missing path to CRITICAL_FILES in tools/build-doctor.cjs and open a follow-up issue. |
Manual DMG when /var/folders is full:
TMPDIR=/Volumes/External\ 01/.tmp \
hdiutil create \
-srcfolder "release/mac-arm64/Voice Gateway.app" \
-volname "Voice Gateway 0.1.0-arm64" \
-anyowners -nospotlight \
-format UDZO -fs HFS+ \
"release/Voice Gateway-0.1.0-arm64.dmg"Run npm run build:mac --verbose to see the full electron-builder log
plus our afterPack output.
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