Get to your first agent fast.

This page is a practical quickstart for deploying Open Voice Agent and creating your first voice agent. It’s intentionally operator-focused: multi-tenant, BYO keys, and realtime voice.

Quickstart

Deploy → configure → create agent.

Use this when deploying on a VPS with separate app and API domains.

Domains

Recommended layout:app.yourdomain.com and api.yourdomain.com.

Set backend env:PUBLIC_URL (API) and APP_PUBLIC_URL (dashboard).

Services

Run Postgres + Redis, apply migrations, then start backend + frontend.

Keep staging and production separated (env files, DBs, webhook URLs).

Keys

Add provider keys per workspace in Settings → Workspace API Keys.

This isolates billing and avoids platform-wide credentials.

Commands (typical self-host)

# Start Postgres + Redis
docker-compose up -d postgres redis

# Backend migrations
cd backend
uv run alembic upgrade head

# Run backend (dev)
uv run uvicorn app.main:app --reload

# Run frontend (new terminal)
cd ../frontend
npm install
npm run dev

Production deployments typically run behind a reverse proxy (TLS) and process manager/container orchestrator.

First agent

Create a workspace, add keys, then create an agent.

The UI requires a workspace before agent creation.

1) Workspaces

Create a workspace for a client to isolate data and keys.

Open Workspaces

2) Workspace API keys

Add Grok/OpenAI keys (and telephony verification secrets if needed) to the selected workspace.

Open Settings

3) Create an agent

Set name + system prompt, select workspaces, then deploy to web widget or phone.

Create an agent

Operations

Health checks and common pitfalls.

Use these to debug deployments quickly.

Health endpoints (API)

Replace api.yourdomain.com with your API host:

curl -fsS https://api.yourdomain.com/health
curl -fsS https://api.yourdomain.com/health/db
curl -fsS https://api.yourdomain.com/health/redis

Realtime key presence probes:/health/grok and /health/openai.

Common issues

Login shows “failed to fetch”: ensure backend CORS_ORIGINS includes the dashboard origin.
Password login returns 404: ensure AUTH_MAGIC_LINK_ONLY=false.
Realtime errors: confirm workspace provider keys are set in Settings for the workspace you selected.
Webhooks not reaching API: verify DNS/TLS and that provider webhooks point to PUBLIC_URL.

Security Contact

API reference

The backend exposes Swagger UI at https://api.yourdomain.com/docs and an OpenAPI spec at https://api.yourdomain.com/openapi.json.