Production-grade Voice AI Infrastructure — deploy, operate, and trust.
🌐 Live: voxforge.brohammad.tech · Status · Demo · Dashboard · API · Case study · Discussions
Refresh this GIF: ./scripts/generate-demo-gif.sh (automated) or record manually and run ./scripts/capture-demo-gif.sh recording.mp4 — see recording checklist.
VoxForge is an open-source platform for building and operating enterprise voice agents. Unlike chatbot wrappers, it ships a complete voice stack: transport, orchestration, knowledge retrieval, tool execution, per-turn evaluation, session replay, human handoff, and an operator dashboard — all deployable to your own infrastructure.
v1.0.0-rc.1 is live in production with HTTPS, automated tests, and a public demo. Release notes →
| Layer | Capabilities |
|---|---|
| Voice | WebSocket gateway, programmatic onboarding API, LiveKit WebRTC |
| Intelligence | LangGraph orchestrator (planner, safety, executor + conditional tools, critic, coordinator) |
| Knowledge | Document upload, chunking, pgvector search, citation grounding |
| Tools | Builtin tools + MCP server discovery at runtime |
| Operations | Dashboard, latency analytics, alerts, policy presets, SAML SSO |
| Trust | Per-turn evaluation, signed replay links, human handoff queue |
| Deploy | Docker Compose, NGINX, Let's Encrypt, health/readiness probes |
One VoicePipelineService powers every transport — no duplicated business logic across WebSocket, REST onboarding, or WebRTC.
| VoxForge | Typical chatbot demo | |
|---|---|---|
| Deploy | Self-hosted Docker + HTTPS | Vendor lock-in |
| Pipeline | STT → agent → TTS + evaluation | LLM wrapper only |
| Operations | Dashboard, replay, handoff queue | Logs in a black box |
| Tests | 426 collected (verified snapshot) — project metrics | Unknown |
| Extensibility | MCP tools, swappable providers | Hardcoded integrations |
Compared to managed platforms (Vapi, Retell) you get data sovereignty and no per-minute platform tax. Compared to frameworks (LiveKit Agents, Pipecat, LangGraph alone) you get a batteries-included product with auth, dashboard, and deploy scripts.
Minimal curl walkthrough (no LiveKit): examples/hello-voice
- Engineers building voice agents who want a real architecture, not a prototype
- Operators who need replay, metrics, and escalation workflows
- Teams evaluating self-hosted voice AI before committing to a SaaS vendor
- Contributors looking for a well-tested, documented open-source codebase
Prerequisites: Python 3.12+, Docker, uv (recommended)
git clone https://github.com/Brohammad/VoxForge.git
cd VoxForge
cp .env.example .env
uv sync # or: pip install -e ".[dev,livekit]"
docker compose up -d postgres redis
alembic upgrade head
uvicorn voxforge.main:app --reload --app-dir srcMock STT/LLM/TTS providers work without API keys. Open /demo and click Start talking, Run trust loop, or Run one-click sample call.
Detailed walkthrough: docs/ONBOARDING.md
# Health
curl http://localhost:8000/api/v1/health
# Register + login (dashboard uses the same endpoints)
curl -X POST http://localhost:8000/api/v1/auth/register \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"your-secure-password","full_name":"You"}'
# One-click demo (no auth required when DEMO_ENABLED=true)
curl -X POST http://localhost:8000/api/v1/demo/quickstartDeploy to a fresh Ubuntu 24.04 VPS with HTTPS in one flow:
./scripts/setup-production-env.sh your-domain.example
# Edit .env.production if needed (providers, LiveKit)
./deploy.sh initdeploy.sh handles environment validation, Docker image build, NGINX + Certbot TLS, health-gated startup, and optional workers (knowledge, LiveKit, Prometheus/Grafana).
./deploy.sh status # service health
./deploy.sh backup # Postgres backup
./deploy.sh smoke # local prod validation (no TLS)| Guide | Description |
|---|---|
| Deployment guide | Full VPS setup |
| Runbook | Day-2 operations |
| Public deployment | Live instance reference |
| Verification checklist | Post-deploy QA |
Reference deployment: https://voxforge.brohammad.tech (Let's Encrypt, smoke-tested)
Client
→ Transport (WebSocket / LiveKit WebRTC / REST onboarding)
→ VoicePipelineService
→ Agent Orchestrator (LangGraph)
→ MCP Tool Router + Knowledge RAG + Memory
→ Evaluation Engine
→ Replay / Handoff / Dashboard
| Module | Responsibility |
|---|---|
| Auth | JWT, RBAC, organizations, API keys, SAML SSO |
| Voice Gateway | WebSocket streaming, session lifecycle |
| Agent Orchestrator | Multi-agent pipeline with safety and critic stages |
| Knowledge | Ingestion, embedding, semantic search, citations |
| Memory | Semantic retrieval, summarization (pgvector) |
| Handoff | Human escalation queue, signed replay URLs |
| Evaluation | Per-turn latency, quality, tool, and cost scoring |
| Dashboard | Operator UI + analytics API |
| LiveKit Gateway | WebRTC token generation and worker dispatch |
Built as a modular monolith with Clean Architecture — clear module boundaries without microservice operational overhead.
Architecture diagrams · Voice pipeline · Architecture index · ADRs
| Component | Technology |
|---|---|
| API | FastAPI, Uvicorn, Python 3.12 |
| Agents | LangGraph, LangChain |
| Database | PostgreSQL 16 + pgvector |
| Cache / queues | Redis |
| Observability | OpenTelemetry, Prometheus, structured logging |
| Frontend | Static dashboard + landing (no Node build step) |
| Deploy | Docker Compose, NGINX, Certbot |
| CI | pytest, Playwright, ruff, pip-audit, gitleaks |
Swap providers via environment variables — no code changes:
| Role | Options | Default (local) |
|---|---|---|
| STT | mock, deepgram |
mock |
| LLM | mock, openai |
mock |
| TTS | mock, cartesia |
mock |
| Embeddings | mock, openai |
mock |
STT_PROVIDER=deepgram
LLM_PROVIDER=openai
TTS_PROVIDER=cartesia
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...Production validation enforces real providers when DEMO_ENABLED=false.
make test # non-browser suite (see docs/project-metrics.md)
make test-browser # Playwright UI journeys
make test-unit # Unit tests only
make test-integration # Integration tests
make test-feature # Feature scenarios
make test-failure # Failure-mode tests
make test-cov # Coverage report (70% gate)
ruff check src tests # Lint| Layer | Location | Count |
|---|---|---|
| Unit | tests/unit/ |
Core logic |
| Integration | tests/integration/ |
DB, Redis, providers |
| Feature | tests/feature/ |
End-to-end flows |
| Browser | tests/browser/ |
Landing, demo, dashboard, KB |
| Failure | tests/failure/ |
Provider errors, timeouts |
CI runs the full suite on every push to main. See the canonical
project metrics and testing strategy.
src/voxforge/ Application code (Clean Architecture)
core/ Domain interfaces and models
modules/ Feature modules (auth, voice, knowledge, …)
infrastructure/ Providers, HTTP, persistence, LiveKit
dashboard/ Operator UI (static HTML/JS)
public/ Landing page, demo, assets
deploy/ NGINX templates, TLS config
docs/ Architecture, deployment, pilot guides
tests/ Unit → browser test pyramid
scripts/ Deploy, backup, benchmarks, smoke tests
Full index: docs/README.md
| Topic | Link |
|---|---|
| Quick start | docs/ONBOARDING.md |
| Configuration | docs/CONFIGURATION.md |
| Deployment | docs/deployment/ |
| Architecture | docs/architecture/ |
| Operations | docs/operations/ |
| Testing | docs/testing/ |
| Pilot program | docs/pilot/ |
| Demo scripts | docs/demo/ |
| FAQ | docs/FAQ.md |
| Community Q&A | GitHub Discussions |
| Roadmap | docs/ROADMAP.md |
| Releases | docs/release/ |
Do I need API keys locally?
No — mock providers work out of the box.
Is LiveKit required?
No — WebSocket voice works without it. LiveKit adds browser WebRTC.
Can I self-host in production?
Yes — ./deploy.sh init on Ubuntu 24.04 with automatic HTTPS.
What's not production-ready yet?
Zendesk ticketing is implemented but still needs live sandbox verification; Freshdesk is not implemented. Use internal/mock knowledge. Dashboard login uses HttpOnly cookies (JWT paste still works as Bearer override). See known limitations.
Contributions welcome — especially docs, tests, and provider adapters.
- Fork the repo
- Create a branch (
git checkout -b fix/issue) - Run
make testandruff check src tests - Open a PR using the template
See CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md
Questions: GitHub Discussions (Q&A). Search existing threads first. Bugs and features stay on issues.
Good first issues: https://github.com/Brohammad/VoxForge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
MIT — see LICENSE.