Skip to main content

​
Quick start

By the end of this guide you have a running daemon, an open dashboard, and a Python script that exercises the inference factories so you can confirm provider keys resolve and costs land in the dashboard.

​
Prerequisites

  • Python 3.11 or later
  • An API key for at least one cloud provider (Deepgram, OpenAI, Anthropic, Groq, Cartesia, ElevenLabs, or AssemblyAI)

​
1. Install

pipx install 'voicegateway[cloud,dashboard]'
Or if you prefer uv: 
uv tool install 'voicegateway[cloud,dashboard]'
The cloud extra pulls every cloud provider SDK; the dashboard extra ships the prebuilt React bundle and the dashboard endpoints. For a minimal install of one provider only, see Installation.

​
2. Onboard

voicegw onboard
Five questions, four with working defaults (press Enter to accept):
  1. Project name (default: default).
  2. Provider (default: openai).
  3. API key (no default; paste yours).
  4. Port (default: 8080).
  5. Install daemon? (default: yes).
The wizard writes ~/.config/voicegateway/voicegw.yaml, registers the daemon with your OS service manager (LaunchAgent on macOS, systemd --user on Linux, Scheduled Task on Windows), and starts it.

​
3. Open the dashboard

voicegw dashboard
That opens your browser at the daemon URL (default http://127.0.0.1:8080). The daemon serves the React UI at /, the dashboard API at /api/*, and the public HTTP API at /v1/* on the same port.

​
4. Verify the inference factories

Create demo.py: 
from voicegateway.inference import STT, LLM, TTS

# Each call resolves provider/model -> loads the SDK -> wraps with
# cost-tracking and latency middleware. AgentSession would consume
# them directly; here we print to confirm wiring.
stt = STT("openai/whisper-1")
llm = LLM("openai/gpt-4.1-mini")
tts = TTS("openai/tts-1")

print("STT:", stt)
print("LLM:", llm)
print("TTS:", tts)
Run it: 
python demo.py
You should see three instantiated provider objects. VoiceGateway resolved the provider/model strings, loaded the correct SDKs, and wrapped each instance with cost-tracking and latency middleware.

​
5. See costs in the dashboard

Trigger one call (any request that uses the inference factories above) and refresh the dashboard at http://127.0.0.1:8080/costs. The row shows the model, provider, modality, and the per-call cost in USD with the pricing source attribution (voice-prices@<version> for cloud models, voicegateway-local for self-hosted). In the terminal: 
voicegw costs
voicegw status
voicegw logs

​
Add a project

Multiple agents share one daemon? Give each its own project entry in voicegw.yaml so cost rows and provider keys stay separated: 
projects:
  my-agent:
    name: My First Agent
    daily_budget: 5.00
    providers:
      deepgram:
        api_key: ${MY_AGENT_DEEPGRAM_KEY}
      openai:
        api_key: ${MY_AGENT_OPENAI_KEY}

default_project: my-agent
The inference factories pick the project up automatically. Override per-context with set_project("my-agent") from voicegateway.core.active_project when you need to.

​
Add fallbacks

Resolver-time fallback chain in voicegw.yaml: 
fallbacks:
  stt: [deepgram/nova-3, openai/whisper-1]
  llm: [openai/gpt-4.1-mini, anthropic/claude-sonnet-4-5]
  tts: [openai/tts-1, elevenlabs/eleven_turbo_v2_5]
Walk the chain at startup by trying each model with STT/LLM/TTS(model_id) and using the first one whose provider plugin imports cleanly. Once AgentSession starts, the resolved model is used for the whole call.

​
Next steps