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

# Get started

> Install VoiceGateway, run the onboarding wizard, see your first provider call land in the dashboard. 60 seconds, excluding the time it takes to fetch your provider API key.

# 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

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

```bash theme={null}
pipx install 'voicegateway[cloud,dashboard]'
```

```bash theme={null}
uv tool install 'voicegateway[cloud,dashboard]'
```

## 2. Run the wizard

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

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

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

```python theme={null}
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](/guide/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:

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