Skip to main content

​
Get started

VoiceGateway runs as a long-lived background daemon that serves both the HTTP API and the dashboard on a single port. From a fresh machine to your first inference call: one curl, one wizard. The 60-second clock starts when you paste the install command and stops when your first call shows up in the dashboard, excluding the time spent fetching your provider API key.

​
1. Install

curl -fsSL https://voicegateway.mahimai.ca/install.sh | bash
What the installer does:
  • Detects macOS, Linux, or WSL on Windows. Refuses cleanly on anything else.
  • Verifies Python 3.11 or newer is installed. Refuses with package manager pointers if not (does not auto-install Python).
  • Picks uv tool install when uv is on PATH, otherwise installs pipx if missing and runs pipx install voicegateway[cloud,dashboard].
  • Asks before any privileged step.
  • Prints the next-step command.
If you prefer not to pipe a remote script: 
pipx install 'voicegateway[cloud,dashboard]'

uv tool install 'voicegateway[cloud,dashboard]'

​
2. Run the wizard

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 then:
  • Validates your API key against the provider with a 5-second timeout. On timeout, the wizard continues with a warning instead of failing.
  • Registers a user-scoped daemon (LaunchAgent on macOS, systemd --user unit on Linux, Scheduled Task on Windows) and starts it.
  • Optionally runs voicegw smoke-test and confirms the pipeline.
  • Prints the dashboard URL (default http://127.0.0.1:8080) and the next-step commands.
Pressing Ctrl+C at any point cleans up partial state. Re-running the wizard is always safe.

​
3. Open the dashboard

voicegw dashboard
That opens your browser at the daemon URL. The daemon already serves the dashboard at /, the dashboard API at /api/*, and the public HTTP API at /v1/*, all on the port the wizard collected. Use voicegw dashboard --no-open to print the URL without launching a browser (useful over SSH). Other lifecycle commands: 
voicegw status        # daemon + provider status
voicegw doctor        # numbered punch list with fix steps
voicegw logs          # tail recent activity
voicegw stop          # bring the daemon down
voicegw restart       # restart the daemon

​
4. Wire it into your LiveKit agent

Swap one import line: 
from voicegateway.inference import STT, LLM, TTS

stt = STT("deepgram/nova-3")
llm = LLM("openai/gpt-4.1-mini")
tts = TTS("openai/tts-1")
Pass each to AgentSession exactly as you would the upstream livekit.agents.inference equivalents. Cost tracking, latency monitoring, and per-session correlation happen behind the scenes. See Quick start for the full integration walkthrough.

​
Troubleshooting

voicegw doctor is the first place to look for first-call issues. It prints a numbered punch list with concrete fix steps for each failed check. No stack traces. No bare “see docs” pointers. The three most common things that block first-call:

​
Python 3.11+ is missing

install.sh refuses on Python below 3.11 because the cloud provider SDKs have already moved past 3.10. Install Python first, then re-run install.sh. VoiceGateway will not auto-install Python. That choice is left to your OS package manager so we never silently shadow a system Python or break a virtualenv you cared about.

​
pipx is missing or not on PATH

install.sh installs pipx automatically when it can (or uses uv if available). Two failure modes are common:
  1. pipx installed but pipx is not on your PATH yet. Open a fresh shell and try again, or add ~/.local/bin to your PATH: 
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
exec $SHELL
  2. The installer printed pipx ensurepath and exited cleanly. Your installed-as-user directory is registered but the current shell did not pick it up yet. Open a new terminal tab and re-run voicegw onboard.

​
Provider key is invalid

The wizard validates your key against the provider with a 5-second timeout. If validation returns 401 unauthorized or similar:
  1. Double-check the key in your provider dashboard. The most common cause is a missing character, a stray newline, or the wrong project selected when you generated the key.
  2. Re-run the wizard. It is idempotent: any partial state from a previous attempt is overwritten cleanly.
  3. Run voicegw doctor. The provider-key validation check prints exactly which key was rejected and what to verify.