> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicegateway.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# voicegw serve / start / stop / restart

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

# 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

```bash theme={null}
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

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

```bash theme={null}
# 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
```

<h2 id="start">
  `voicegw start`
</h2>

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

```bash theme={null}
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).

<h2 id="stop">
  `voicegw stop`
</h2>

Bring the OS-installed daemon down.

```bash theme={null}
voicegw stop
```

<h2 id="restart">
  `voicegw restart`
</h2>

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).

```bash theme={null}
voicegw restart
```

<h2 id="daemon-logs">
  `voicegw daemon-logs`
</h2>

Tail the OS-native daemon log stream.

```bash theme={null}
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.

<h2 id="uninstall">
  `voicegw uninstall-daemon`
</h2>

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
docker compose up -d
```

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

## Related commands

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