Installation

System requirements

• Python 3.11 or later
• SQLite 3.35+ (ships with Python; used for cost tracking and request logs)
• macOS, Linux, or WSL on Windows. Native Windows is supported via Scheduled Tasks for the daemon; the rest of the docs assume a POSIX shell.
• Docker (optional, for containerised deployments)

Recommended: curl-bash one-liner

curl -fsSL https://voicegateway.mahimai.ca/install.sh | bash

The installer:

• Detects your OS (macOS / Linux / WSL).
• Verifies Python 3.11+ is installed (refuses with package-manager pointers if not; does not auto-install Python).
• Picks uv tool install if uv is on PATH, otherwise installs pipx and runs pipx install voicegateway[cloud,dashboard].
• Asks before any privileged step.

After install, run voicegw onboard. See Get started for the 60-second walkthrough.

pipx (manual)

pipx install 'voicegateway[cloud,dashboard]'

pipx installs VoiceGateway into its own virtualenv so the voicegw binary lands on your PATH without polluting your system Python.

uv (manual)

uv tool install 'voicegateway[cloud,dashboard]'

uv tool install is faster than pipx and uses the same per-tool-venv model. If you have uv already, prefer this.

Install extras

VoiceGateway uses optional extras to keep the install lightweight. Only the provider SDKs you need are installed.

You can combine extras:

pipx install 'voicegateway[cloud,dashboard,mcp]'

Or install individual provider SDKs:

pipx install 'voicegateway[openai,deepgram]'

From source

git clone https://github.com/mahimailabs/voicegateway.git
cd voicegateway
pip install -e ".[dev]"

The dev extra includes test dependencies (pytest, pytest-asyncio, pytest-cov, ruff, mypy).

Running from source ships the React frontend as source. Build it:

cd src/dashboard/frontend
npm install
npm run build

The daemon mounts src/dashboard/frontend/dist/ at / once that exists.

Docker

VoiceGateway ships a docker-compose.yml for running the daemon (serving both the HTTP API and the dashboard):

# Daemon (HTTP API + dashboard on one port)
docker compose up -d

# Plus Ollama (for local LLM)
docker compose --profile local up -d

The default Docker setup exposes port 8080: the daemon serves /v1/* (HTTP API), /api/* (dashboard API), and / (React UI) on that port. Mount your config and set environment variables:

docker compose up -d \
  -e DEEPGRAM_API_KEY=your-key \
  -e OPENAI_API_KEY=your-key \
  -v ./voicegw.yaml:/app/voicegw.yaml

Verify the install

voicegw --version
voicegw status

If voicegw is not on your PATH, run:

python -m voicegateway.cli --version

For pipx, you may need pipx ensurepath && exec $SHELL.

Upgrading

pipx upgrade voicegateway

Or with uv:

uv tool upgrade voicegateway

After upgrading, check for config schema changes:

voicegw init --diff

Troubleshooting

ModuleNotFoundError: No module named 'deepgram'

You installed the base package without the provider extra. Install the extra you need:

pipx install 'voicegateway[deepgram]'

ConfigError: No voicegw.yaml found

VoiceGateway searches for config in this order:

1. ./voicegw.yaml (current directory)
2. ~/.config/voicegateway/voicegw.yaml
3. /etc/voicegateway/voicegw.yaml

You can also set the VOICEGW_CONFIG environment variable to an explicit path. Run voicegw init to generate a starter config or voicegw onboard to be walked through it.

Next steps

• Get started: 60-second walkthrough.
• Quick start: the 5-minute version that exercises the inference factories.
• First agent: build a working agent.
• Environment variables: all supported env vars.