Skip to main content
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.

​
Usage

​
Options

​
Behaviour

  1. Load the gateway configuration.
  2. Build the FastAPI app: 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

​
voicegw start

Bring the OS-installed daemon up. The daemon must be installed first (via voicegw onboard or voicegw onboard --install-daemon).
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 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 daemon-logs

Tail the OS-native daemon log stream.
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.
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:
If uvicorn is missing, voicegw serve exits with an error message pointing at this install command. VoiceGateway is framework-agnostic and does not bundle provider or local-model wheels. Install the provider plugins your agent uses in your own agent environment (you likely already have them), for example pip install livekit-plugins-openai livekit-plugins-deepgram. VoiceGateway meters those instances by model_id via voice-prices.

​
Docker

The serve command is the default entrypoint in the Docker image:
The container binds port 8080 by default (override via VOICEGW_PORT). voicegw onboard | voicegw dashboard | voicegw status | voicegw mcp