Documentation
The Brisvox documentation is a book: quickstart, concepts, configuration, telephony, operations, benchmarks and
reference. It is built from the docs/ folder of the repository, so the same text is on GitHub and in
the book.
Last updated:
Start here
From nothing to a call you can talk to.
- IntroductionWhat Brisvox is and how the parts fit
- Run the server with an example agentBuild the server, run an example agent, call it
- Write an agent with the Python or TypeScript SDKYour own tools and application logic
- Docker and composeRun it with an agent file and your keys
- A fully local assistantsherpa-onnx, Ollama and Kokoro: nothing leaves the machine
Concepts
Short pages for the mental model.
Build and configure
The agent file, the tools and the callers.
- Agent file referenceEvery key: agent, stt, llm, tts, turn, interruption, tools, s2s
- Tool-calling contractParallel and chained calls, retries, idempotency, MCP
- ProvidersConfig names and cargo features for every adapter
- Speech-to-speech modelsOpenAI Realtime and Gemini Live as one stage
- Turkish supportNormalisation, numbers, providers that handle Turkish
Connect callers
Phone lines, browsers and your own clients.
- TelephonyDTMF, transfer, answering machines
- Twilio Media StreamsSetup and details
- Telnyx media streamingSetup and details
- SIP trunkThe listener behind the sip feature
- Browser client, @brisvox/webWebRTC with an automatic WebSocket fallback
- WebSocket protocolFor your own client
- RTVIConnect Pipecat's client SDKs
Run in production
Deploying, watching and securing the server.
- OperationsEnvironment variables, health, metrics, usage and cost, admission
- Deploying in a containerContainers, one-port hosts, TURN, TLS, scaling
- Security and authenticationThreat model and the deployment checklist
- Privacy and recordingRecording, encryption at rest, retention, redaction
- Grafana dashboardOne row per operator question
Reference and design
Why it behaves the way it does.
- ArchitectureCrates, frames, epochs, pools
- Production pipeline designStage by stage, with the failure policy
- Agent protocolThe wire protocol between the server and an SDK agent
- Latency design and measurementsBudget, measurements, capacity
- Testing and the quality gateDeterministic simulation, chaos, isolation tests
What to build with
The default build has no providers and no listeners beyond the websocket: you choose cargo features for what
you want to run. The prebuilt binaries and the container image are built with
all-providers,call-control,smart-turn-ort,mcp,webrtc.
| Goal | Cargo features | Read |
|---|---|---|
| A voice button on a website (WebRTC with a WebSocket fallback) | all-providers,smart-turn-ort,webrtc | Web assistant example |
| A phone number through Twilio or Telnyx (transfer, DTMF, hang-up) | all-providers,call-control,smart-turn-ort | Phone receptionist example |
| A SIP trunk | all-providers,call-control,smart-turn-ort,sip | Telephony |
| Fully local speech, no API key | provider-sherpa-onnx,provider-openai-compatible,provider-openai-speech,smart-turn-ort,webrtc | A fully local assistant |
| Your own tools in Python or TypeScript | The features of the goal above; tools come from an SDK process | Booking agent example |
| Your own tools in Rust, in one binary | Your crate depends on brisvox with the provider features your agent file names | Rust tools example |
For AI coding agents
Point your agent at these and it can work on a Brisvox project without prior knowledge.
- llms.txt of the repository: the facts to know first and one line per document
- llms-full.txt of the repository: the user guide in one file
- The Brisvox Agent Skill: the workflow and the common traps
- JSON Schema of the agent file, for editors and tools
- llms.txt of this site and llms-full.txt: this site's content as plain text