Requirements
- Python 3.11 or later
- macOS, Linux, or WSL on Windows
Framework extras
Install the extra that matches your agent framework. The core package is framework-neutral:import voicegateway imports neither LiveKit Agents nor
Pipecat.
Provider plugins (LiveKit)
VoiceGateway is framework-agnostic and does not bundle provider wheels. You install the LiveKit provider plugins your agent uses, exactly as you would without VoiceGateway (you likely already have them). VoiceGateway meters those native instances bymodel_id through voice-prices.
attach() and guard() error messages point at the upstream wheel (for
example livekit-plugins-openai), not a VoiceGateway extra. Install the wheel
named in the error into your agent environment.Provider extras (Pipecat)
For Pipecat, installvoicegateway[pipecat] and then install provider service
extras directly from Pipecat. VoiceGateway wraps the native Pipecat services you
already configure.
Additional extras
VoiceGateway ships four runtime extras (dev is separate, for contributors:
see Install from source).
There is no standalone
mcp extra: voicegw mcp ships inside dashboard
(and so inside collector too). There are no per-provider or local-model
extras either. VoiceGateway meters native
provider instances and local/* and ollama/* model ids for free by
model_id, so you bring the provider plugins and local runtimes yourself. For
local models install the runtime directly: Whisper with
pip install faster-whisper, Kokoro with pip install kokoro-onnx onnxruntime,
Piper with pip install piper-tts.
You can combine any extras. To install the everything set:
Install from source
dev extra includes pytest, ruff, and mypy. To build the dashboard
frontend from source:
Docker
docker compose up has no -e or -v flags. Provider keys and volume
mounts belong in the compose file’s environment:/volumes: blocks, or in
a .env file Compose reads automatically. This repo’s docker-compose.yml
does both already: it mounts ./voicegw.yaml and reads keys like
${DEEPGRAM_API_KEY} from the environment.
Run
voicegw init first. On images at or below 0.22.3 a missing config file
is fatal: the container exits at boot. From 0.24.0 it is only a warning and the
daemon boots on built-in defaults, but a default-config daemon has no providers,
models, or projects declared, so you want the file regardless.The CLI is stricter than the container either way. voicegw serve, costs,
logs, and status all resolve a config and raise ConfigError when there is
none, so a mistyped --config stays a hard error rather than silently starting
on defaults..env, health checks, persistent
storage): Docker deployment.
Verify
voicegw is not on your PATH after a uv pip install, activate the
environment, or call the entry point directly: ./.venv/bin/voicegw --version
(.venv\Scripts\voicegw.exe --version on Windows).
Upgrading
voicegw init only takes --output/-o and --full; there is no --diff
flag.
Troubleshooting
ModuleNotFoundError: No module named 'deepgram'
Your agent is missing the Deepgram plugin. VoiceGateway does not install provider
wheels, so install the one your agent uses:
ConfigError: No voicegw.yaml found
Run voicegw init to generate a starter config, or set VOICEGW_CONFIG to
an explicit path. See config discovery
order for the
default search path.
Next steps
- Quickstart: five-minute path from install to first cost row.
- First agent: a complete worked agent with
attach()andguard(). - Frameworks and extras: framework-neutral core explained.