Run the VoiceGateway daemon. serve runs in the foreground; start, stop, restart, daemon-logs, and uninstall-daemon manage the OS-installed service.

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

Shell

voicegw serve [OPTIONS]

Options

Flag	Short	Type	Default	Description
`--config`	`-c`	`string`	auto	Path to `voicegw.yaml`. Auto-discovered if omitted.
`--host`		`string`	`serve.host` or `0.0.0.0`	Bind address. Override with `127.0.0.1` to restrict to localhost.
`--port`		`integer`	`serve.port` or `8080`	Port number to listen on.

Behaviour

Load the gateway configuration.
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.
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

Shell

# 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` {#start}

Bring the OS-installed daemon up. The daemon must be installed first (via voicegw onboard or voicegw onboard --install-daemon).

Shell

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` {#stop}

Bring the OS-installed daemon down.

Shell

voicegw stop

`voicegw restart` {#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).

Shell

voicegw restart

`voicegw daemon-logs` {#daemon-logs}

Tail the OS-native daemon log stream.

Shell

voicegw daemon-logs [--tail N]

Flag	Short	Type	Default	Description
`--tail`	`-n`	`integer`	`100`	Number 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` {#uninstall}

Remove the daemon registration. The config file at ~/.config/voicegateway/voicegw.yaml and the SQLite database (~/.config/voicegateway/voicegw.db by default) are preserved.

Shell

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:

Shell

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:

Shell

docker compose up -d

The container binds port 8080 by default (override via VOICEGW_PORT).

voicegw onboard: writes the config and installs the daemon in one go.
voicegw dashboard: open the dashboard in your browser once the daemon is up.
voicegw status: verify the daemon is serving the expected providers.
voicegw mcp: start the MCP server for coding agents.

voicegw serve / start / stop / restart

On this page