Quickstart

By the end of this page you have VoiceGateway installed, one attach() call in your agent, and a per-modality cost row on screen for a real call. This is the agent layer. The SFU and SIP layers have different prerequisites and are covered in what you can profile.

Before you start

Python 3.11 or later
API keys for one STT, one LLM, and one TTS provider
LiveKit only: a LiveKit project. The agent worker cannot start without one, and there is no way around this. A free LiveKit Cloud project or a local livekit-server --dev both work.

Install

Install the extra for your framework, then the provider plugins your agent uses. VoiceGateway bundles no provider wheels; it meters the native instances you already construct.

LiveKit
Pipecat

pip install "voicegateway[livekit,dashboard]"
pip install "livekit-agents[silero]"
pip install livekit-plugins-openai livekit-plugins-deepgram livekit-plugins-cartesia

pip install "voicegateway[pipecat,livekit,dashboard]"
pip install "pipecat-ai[openai,deepgram,cartesia,daily]"

The dashboard extra pulls FastAPI and uvicorn, which voicegw serve needs in step 4.

The livekit extra is in the Pipecat command on purpose. The voicegw CLI imports its LiveKit diagnostics at startup, so every subcommand needs that extra even on a Pipecat-only deployment. Your agent still imports no LiveKit code. See what you can profile.

Installation has the full extras table, Docker, and source builds.

Set your environment variables

LiveKit
Pipecat

# Required. The agent worker connects to LiveKit before it does anything else.
export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=your-livekit-key
export LIVEKIT_API_SECRET=your-livekit-secret

# Read implicitly by the plugin classes below.
export DEEPGRAM_API_KEY=your-deepgram-key
export OPENAI_API_KEY=your-openai-key
export CARTESIA_API_KEY=your-cartesia-key

Running livekit-server --dev locally instead? Use LIVEKIT_URL=ws://localhost:7880, LIVEKIT_API_KEY=devkey, LIVEKIT_API_SECRET=secret.

export DEEPGRAM_API_KEY=your-deepgram-key
export OPENAI_API_KEY=your-openai-key
export CARTESIA_API_KEY=your-cartesia-key

Pipecat has no LiveKit dependency, so no LIVEKIT_* variables are needed unless you use a LiveKit transport.

Add attach() to your agent

One call, placed before the session or pipeline starts. Every native provider stays exactly as it is.

LiveKit
Pipecat

# agent.py
from livekit.agents import Agent, AgentSession, WorkerOptions, cli
from livekit.plugins import cartesia, deepgram, openai

import voicegateway


async def entrypoint(ctx):
    await ctx.connect()

    session = AgentSession(
        stt=deepgram.STT(model="nova-3"),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=cartesia.TTS(model="sonic-3"),
    )

    # One call. Every STT / LLM / TTS request is metered from here.
    voicegateway.attach(session, project="my-agent")

    await session.start(
        agent=Agent(instructions="You are a helpful voice assistant."),
        room=ctx.room,
    )


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

# agent.py
import asyncio
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.services.cartesia.tts import CartesiaTTSService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService

import voicegateway


async def main():
    pipeline = Pipeline([
        DeepgramSTTService(api_key=os.environ["DEEPGRAM_API_KEY"]),
        OpenAILLMService(
            api_key=os.environ["OPENAI_API_KEY"],
            model="gpt-4o-mini",
        ),
        CartesiaTTSService(
            api_key=os.environ["CARTESIA_API_KEY"],
            voice_id="your-voice-id",
        ),
    ])
    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
        ),
    )

    # One call. Every STT / LLM / TTS request is metered from here.
    voicegateway.attach(task, project="my-agent")

    await PipelineRunner().run(task)


if __name__ == "__main__":
    asyncio.run(main())

enable_metrics=True and enable_usage_metrics=True are required. Without them Pipecat emits no usage frames, attach() records nothing, and the dashboard stays empty with no error to tell you why.

Start the daemon

In a second terminal:

voicegw init     # writes voicegw.yaml; the daemon refuses to start without one
voicegw serve    # serves the API and the dashboard on http://localhost:8080

voicegw init writes a minimal config with cost_tracking already enabled, pointing at the same default database attach() writes to. That is what connects your agent to the dashboard with no further wiring.Open http://localhost:8080 in a browser. The Costs page is empty until the first call completes. Leave it open.

voicegw dashboard does not start anything. It reads serve.host and serve.port from your config and opens a browser at that address, so it is a convenience once the daemon is already running. Add --no-open to print the URL instead, which is what you want over SSH.

Run the agent and place a call

LiveKit
Pipecat

python agent.py dev

Now get audio into the room. The quickest route is the LiveKit Playground, which connects to your project and gives you a microphone. Say something, then end the call.

python agent.py

Speak through whichever transport you wired into the pipeline. Rows are written as the pipeline runs and finalized when it ends.

Read the cost rows

Refresh the dashboard and open the Costs page. It aggregates by model:

Column	What it means
Model	the model id your plugin reported
Requests	how many calls hit that model
Cost	USD, priced through `voice-prices`
Pricing source	which catalog entry produced that number

For one row per request, use the terminal:

voicegw logs     # time, project, modality, model, cost, latency, status
voicegw costs    # totals per provider and project, plus the pricing source in use
voicegw status   # daemon and provider health

Nothing showed up?

Symptom	Cause
LiveKit worker exits at startup with a `ValueError`	`LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` unset. The worker validates these before it runs your entrypoint
Call connects, dashboard stays empty (Pipecat)	`enable_metrics` / `enable_usage_metrics` not set on `PipelineParams`
`voicegw serve` says dashboard dependencies are not installed	install the `dashboard` extra
`ConfigError: No voicegw.yaml found`	run `voicegw init` first. `attach()` needs no config file, but the daemon does
Browser cannot connect after `voicegw dashboard`	nothing is serving. `voicegw dashboard` opens a URL, it does not start the daemon
Rows appear with zero cost	a local model (`local/`, `ollama/`), which is priced at zero by design

More cases in Troubleshooting.

Next: attach() for the full signature, guard() for fallback and budgets, or first agent for a complete worked file.

Get started

Understanding VoiceGateway

Before you start

Nothing showed up?

Next

​Before you start

​Nothing showed up?

​Next

Before you start

Nothing showed up?

Next