Skip to main content

​
voicegw serve / start / stop / restart

The daemon is the single long-lived process behind VoiceGateway. It serves the HTTP API (/v1/*), the dashboard API (/api/*), and the React SPA (/) on a single port. Five lifecycle commands manage it.

​
voicegw serve

Run the daemon in the foreground. Useful for development, smoke testing, and Docker entrypoints.

​
Syntax

voicegw serve [OPTIONS]

​
Options

FlagShortTypeDefaultDescription
--config-cstringautoPath to voicegw.yaml. Auto-discovered if omitted.
--hoststringserve.host or 0.0.0.0Bind address. Override with 127.0.0.1 to restrict to localhost.
--portintegerserve.port or 8080Port number to listen on.

​
Behaviour

  1. Load the gateway configuration.
  2. Build the FastAPI app (build_app(gateway)): registers all /v1/* routers, all /api/* dashboard routers, mounts the React SPA at /, mounts the branding directory at /static/branding/*, and wires the MCP SSE transport.
  3. Start uvicorn on the resolved host and port.
The server runs in the foreground; stop with Ctrl+C. For background operation use voicegw start (after voicegw onboard has installed the daemon) or run inside a process supervisor.

​
Examples

# Default bind (uses serve.host / serve.port from config)
voicegw serve

# Override the port for local testing
voicegw serve --port 8090

# Bind to localhost only
voicegw serve --host 127.0.0.1

​
voicegw start

Bring the OS-installed daemon up. The daemon must be installed first (via voicegw onboard or voicegw onboard --install-daemon). 
voicegw start
On macOS this calls launchctl bootstrap; on Linux, systemctl --user start; on Windows, schtasks /Run. Exits 0 on success. Exits 1 if the OS service manager refuses (usually because the service is not installed).

​
voicegw stop

Bring the OS-installed daemon down. 
voicegw stop

​
voicegw restart

Stop, then start. Equivalent to voicegw stop && voicegw start but does both inside one call to the service manager (so race conditions cannot leave the daemon in a half-down state). 
voicegw restart

​
voicegw daemon-logs

Tail the OS-native daemon log stream. 
voicegw daemon-logs [--tail N]
FlagShortTypeDefaultDescription
--tail-ninteger100Number of recent log lines to print.
On macOS this reads ~/Library/Logs/voicegateway/*.log. On Linux, journalctl --user -u voicegateway. On Windows, the Task Scheduler event log.

​
voicegw uninstall-daemon

Remove the daemon registration. The config file at ~/.config/voicegateway/voicegw.yaml and the SQLite database (~/.config/voicegateway/voicegw.db by default) are preserved. 
voicegw uninstall-daemon
The command prints what was removed and what was preserved, plus the manual rm -rf command if you want to wipe state too.

​
Prerequisites

The dashboard extra must be installed so uvicorn is on the import path: 
pipx install 'voicegateway[cloud,dashboard]'
If uvicorn is missing, voicegw serve exits with an error message pointing at this install command.

​
Docker

The serve command is the default entrypoint in the Docker image: 
docker compose up -d
The container binds port 8080 by default (override via VOICEGW_PORT).