QuickVoice: a self-hosted stack for AI phone agents, before its first stable release

The problem QuickVoice addresses: voice agents as inspectable infrastructure

A hosted voice-agent API gives you a phone number, a prompt box and a webhook. It does not give you the call record schema, the retrieval step, or the point where the model provider is chosen. QuickVoice is built for teams that want those decisions inside their own repository. The README frames it as "the open-source Retell alternative for engineering-led teams that want control over the voice-agent stack instead of only consuming a closed hosted API." The scope claimed in the same paragraph is wide: a marketing site, a customer console, an API server, a LiveKit-powered AI worker, telephony integrations, knowledge bases, call logs, outbound campaigns, billing paths, MCP and tool connections, privacy controls and local development tooling, all in one repo. That breadth is the pitch and also the reason to read carefully. A single repository that spans billing, telephony and retrieval has more surface to configure than a single-purpose library, and the README does not hide this: it points readers at a roadmap, draft v0.1.0 release notes and a setup-boundaries section before they evaluate it for production.

How the pieces connect: web, console, Express API, LiveKit worker, telephony

The README includes a Mermaid flowchart that describes the intended data flow. A visitor arrives from GitHub, runs task up:dev, and that single task brings up the marketing site, the customer console and the Express API with its docs. The API talks to Postgres and Redis. From the API the path continues to the AI service and LiveKit worker, and the worker reaches out to Twilio or Telnyx for the actual PSTN leg. Read that diagram as the architecture claim: the API is the control plane for agents, knowledge and campaigns, Postgres holds durable state, Redis sits alongside it, and the worker is the component that terminates media through LiveKit and then hands the call to a telephony provider. The repository topics list both FastAPI and Python alongside Express and Next.js, which is consistent with the split the README describes: a Node and TypeScript web and API layer, plus a separate Python AI runtime with its own virtualenv and its own health endpoint on port 5555. The MCP and tool connections mentioned in the feature list are not given a diagram or a config example in the material provided, so how an agent binds a tool at runtime cannot be confirmed from what is here.

Getting it running: task up:dev and the prerequisites it assumes

The supported path is one command on a Linux environment: task up:dev. Task up and task dev are aliases, and the README warns that Go Task treats spaces as separate task names, so the explicit colon form is preferred. The prerequisites are specific: Bash 4 or newer, Node.js ^20.19 or ^22.13 or >=24 with Corepack, pnpm 9.0.0 activated by the setup task, Python 3 with 3.12 matching CI and the AI runtime image, Docker with the Compose v2 plugin, and Go Task itself. On Debian, Ubuntu or WSL2 the README gives an apt-get line for docker.io, docker-compose-v2, golang-go, python3 and python3-venv, then a usermod for the docker group and a go install for task. It notes that a distribution Node.js package may be older than QuickVoice requires and must be installed separately. The README is direct about hosts: Linux is supported, macOS is supported with current tools but the bundled Bash 3.2 is not sufficient, and Windows requires WSL2 because the Taskfile scripts are Bash-based. Once running, the documented entry points are the console on port 3000, the marketing site on 3001, API health at /api/v1/health on port 5000, API docs at /api/v1/docs, and AI API health on port 5555. The task creates local env files from *.env.dev.example, installs Node dependencies with the frozen lockfile, creates the Python virtualenv, starts Postgres and Redis from docker-compose.dev.yml, runs Prisma migrations, and launches the services. Individual tasks are also exposed: task doctor, task env:dev, task docker:up, task db:migrate, task db:seed with an --email argument, task ci, and task server:dev.

What task up:dev does not prove

The setup-boundaries section is the most useful part of the README, because it draws a line between a clean local start and a working phone agent. The Compose database credentials are dev-only placeholders, quickvoice and quickvoice, and the Postgres and Redis ports are bound to 127.0.0.1. The README states plainly that the placeholder values are enough to inspect local startup paths but do not make provider-backed actions work, and that a successful task up:dev does not prove live calls, OAuth, billing, email delivery, object storage, Pinecone retrieval or production deployment are configured. Real phone calls require LiveKit plus a configured telephony provider and model-provider credentials. That is a genuine limitation rather than a footnote: the default experience exercises the wiring, not the product. A team that reads only the quick start and assumes a green task up:dev means a working agent will be surprised at the first outbound call. The README also asks that production data and credentials be kept out of local issue reproductions, which is a reasonable request given that the generated env files are git-ignored and meant to be edited after the first run.

Billing, email and retrieval are opt-in paths with their own test rituals

Two optional paths are documented in enough detail to act on. For email, a Docker Compose profile starts Mailpit: docker compose -f docker-compose.dev.yml --env-file .env.dev --profile mail up -d mailpit. For billing, the README points to docs/development/stripe-wallet-test-mode.md, described as a guide that keeps wallet and legacy subscription webhook secrets separate and verifies webhook-authoritative crediting, duplicate delivery and refunds against a Stripe sandbox. The phrase webhook-authoritative crediting is worth pausing on. It implies the wallet balance is derived from webhook events rather than from a client-side confirmation, which is the safer design but also the one where duplicate delivery handling matters, and the guide is said to test exactly that. What the material does not give is a schema for the wallet, a list of webhook event types, or an idempotency key strategy. Teams that need to reason about money movement will have to read the code and the Prisma migrations, not the README. Retrieval has the same shape: Pinecone is named once, in the list of things task up:dev does not prove, and no configuration example for it appears in the material provided.

Where QuickVoice is the wrong choice

The README's own project-status note is the strongest signal against early adoption: QuickVoice is under active development and has not published a stable release, and readers are told to review the roadmap and the draft v0.1.0 notes before evaluating it for production. There are no retrieved releases at all. That means no tagged version, no upgrade path between versions, and no compatibility promise. If your team needs a hosted API with a support contract, or if you cannot absorb a schema change in a Prisma migration, this is not the tool to pick this quarter. The host matrix is a second boundary. Windows without WSL2 is unsupported because the orchestration scripts are Bash-based, and macOS users must confirm that a modern Bash appears before /bin/bash on PATH since the scripts use #!/usr/bin/env bash. A third boundary is operational: the repository spans billing, telephony, email, storage and retrieval, so self-hosting means owning credentials for each of those providers. The README lists Google, Stripe, LiveKit, Twilio, Telnyx, SMTP and AWS as the keys you edit into generated env files. That is a real maintenance load, and it is the price of the control the project is selling.

The alternative, and the actual difference in approach

The README names Retell as the thing QuickVoice positions against, describing it as the closed hosted API whose runtime, data, cost and telephony decisions you outsource. The difference is not feature parity, it is where the decisions live. With a hosted API you get a number, a prompt and a webhook, and the call record schema, the retrieval step and the model provider are the vendor's to change. With QuickVoice the API server, the LiveKit worker, the telephony adapter and the database schema are files in your repository, which means you can read the call path and alter it, and also that you inherit the migration and upgrade work. There is a second, quieter alternative that the README does not name: assembling the same stack yourself from LiveKit, an ASR and TTS provider, and your own API. QuickVoice's value in that comparison is the assembled surface (console, campaigns, call logs, wallet) rather than any single component. If you only need a LiveKit worker that joins a room and streams audio, the surrounding console and billing code is weight you would carry without using.

Licence, maintenance cost and what to check before you commit

The repository is MIT-licensed according to its metadata, while the topics list includes agpl. Those two do not agree, and the discrepancy matters for anyone embedding this in a product. Nothing in the supplied material resolves it, so treat the licence as unverified until you read the LICENSE file at the repository root. This is not legal advice; if the distinction between MIT and AGPL changes your distribution plans, that is a question for counsel. On maintenance, the honest position is that the cost is front-loaded. The prerequisites are pinned (pnpm 9.0.0, Node ^20.19 or ^22.13 or >=24, Python 3.12 matching CI), and the README says the setup task installs dependencies with the frozen lockfile, which reduces drift but also means version bumps are deliberate work. Upgrades will mean re-running Prisma migrations and reconciling generated env files against *.env.dev.example, since the generated files are git-ignored and edited by hand. There is no released version to diff against, so the practical upgrade strategy today is to track the main branch and read the draft release notes. Start with task doctor on your intended host, then task up:dev, then one real call with LiveKit and a telephony provider before you let the console's green dashboard convince you anything is production-ready.

Editorial conclusion

Adopt QuickVoice only if you are an engineering-led team willing to run a pre-release codebase and read the Taskfile, the Prisma schema and the draft v0.1.0 notes before trusting any call path. If you need a hosted API with a support contract and a published SLA, it is the wrong tool today, because the README states there has been no stable release. Before committing, verify three things yourself: that task doctor passes on your host, that a real LiveKit plus Twilio or Telnyx credential set completes one inbound and one outbound call end to end, and that the Stripe wallet flow behaves as described in docs/development/stripe-wallet-test-mode.md against a sandbox, not production.

Official sources

1. allgpt-co/QuickVoice on GitHub
2. Issues
3. License: MIT
4. Project website
5. README