VoiceGateway

Quickstart

Install VoiceGateway next to a LiveKit or Pipecat agent, call attach() once, and read what your first call cost.

By the end of this page you have one attach() call in your agent and a cost row on screen for a real call.

You need Python 3.11 or later and API keys for one STT, one LLM and one TTS provider. On LiveKit you also need a project: a free LiveKit Cloud project or a local livekit-server --dev both work.

Install

VoiceGateway bundles no provider plugins. It meters the ones you already construct, so install those next to it.

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

dashboard adds the web server that voicegw serve runs in step 3.

Add attach() to your agent

One call, before the session or pipeline starts. Your providers stay exactly as they are.

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"),
    )
    voicegateway.attach(session, project="my-agent")
    await session.start(agent=Agent(instructions="Be helpful."), room=ctx.room)


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

Set LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET, plus the provider keys (DEEPGRAM_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY). The worker checks the LiveKit ones before it runs your code.

Start the dashboard

In a second terminal:

voicegw init    # writes voicegw.yaml, which the server needs
voicegw serve   # API and dashboard on http://localhost:8080

attach() needs no config file. It writes to ~/.config/voicegateway/voicegw.db, and the config voicegw init writes reads from the same file. That is the whole wiring.

Place a call and read the cost

Run the agent (python agent.py dev on LiveKit) and talk to it. On LiveKit, the Playground gives you a microphone. End the call, then open the Costs page at http://localhost:8080.

From the terminal:

voicegw logs    # one row per request: modality, model, cost, latency
voicegw costs   # totals per provider and project

Nothing showed up

SymptomCause
LiveKit worker exits with a ValueError at startupLIVEKIT_URL, LIVEKIT_API_KEY or LIVEKIT_API_SECRET is unset
Pipecat call connects, dashboard stays emptyenable_metrics or enable_usage_metrics is off
ConfigError: No voicegw.yaml foundRun voicegw init first
The browser cannot connectNothing is serving. voicegw dashboard opens the URL; voicegw serve starts the server
Rows show zero costA self-hosted model (local/*, ollama/*). Those price at zero by design

Introduction

What VoiceGateway measures, the two calls it adds to your agent, and when something else is the better fit.

attach()

The one meter. Binds to a LiveKit AgentSession or a Pipecat PipelineTask and records cost, latency and usage for every STT, LLM and TTS call.

On this page

InstallAdd attach() to your agentStart the dashboardPlace a call and read the costNothing showed up