Quick start
Brisvox runs as one server process. Install it, describe the agent in one TOML or YAML file, and run it. Your own tools live in your application, in Python or TypeScript, or in Rust inside the server binary.
Last updated:
Install the server
No API keys
git clone https://github.com/bilal07karadeniz/brisvox && cd brisvox
docker compose -f deploy/local/compose.yaml up
# then open http://localhost:8088/demo?force=ws A voice agent that runs entirely on your computer: speech recognition, language model and voice, CPU only. Needs Docker, 4 or more cores and 8 GB of memory; the first start downloads about 6.5 GB.
Prebuilt binary
v=v0.1.3; t=x86_64-unknown-linux-gnu # pick your platform
curl -fLO https://github.com/bilal07karadeniz/brisvox/releases/download/$v/brisvox-server-$v-$t.tar.gz
curl -fLO https://github.com/bilal07karadeniz/brisvox/releases/download/$v/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS && tar xzf brisvox-server-$v-$t.tar.gz
cd brisvox-server-$v-$t
python3 scripts/models/fetch_models.py # the Smart Turn model (pinned SHA-256)
./brisvox-server --version Archives for Linux (x86_64, aarch64), macOS (aarch64) and Windows (x86_64), with a SHA256SUMS file. Linux binaries need glibc 2.39 or newer.
Container image
docker run --rm ghcr.io/bilal07karadeniz/brisvox-server:latest --version
# tags: v0.1.3 and latest, for linux/amd64 and linux/arm64 A multi-architecture image with the Smart Turn model inside.
From crates.io
cargo install brisvox-server --locked \
--features all-providers,call-control,smart-turn-ort,mcp,webrtc Needs Rust 1.99 or newer, a C compiler and cmake. The crate defaults are deliberately small: name the features you want.
Describe the agent and run it
[agent]
name = "support-en"
language = "en"
system_prompt = """
You are the voice assistant of Example Shop. Answer in one or two short spoken sentences.
"""
tools = ["lookup_order"]
[turn]
policy = "adaptive" # Smart Turn decides; fallback_silence_ms ends an undecided pause
[interruption]
preset = "recommended"
backchannels = ["en"] # "yeah", "uh-huh" do not interrupt the bot
[stt]
provider = "deepgram"
api_key_env = "DEEPGRAM_API_KEY"
[llm]
provider = "openai"
api_key_env = "OPENAI_API_KEY"
[tts]
provider = "cartesia"
api_key_env = "CARTESIA_API_KEY"
voice = "replace-with-a-cartesia-voice-id" export DEEPGRAM_API_KEY=... OPENAI_API_KEY=... CARTESIA_API_KEY=...
brisvox-server check agent.toml --require-secrets # validates offline, line and column per problem
BRISVOX_AGENT_FILE=agent.toml brisvox-server # websocket on :8080 API keys come from the environment variable a provider table names, never from the agent file. More starting points are in examples/agents; every key is in the configuration reference.
Add your own tools
Python
from brisvox_agent import Agent
agent = Agent("luigi", system_prompt="You are Luigi's host.", greeting="Hi, Luigi's here!")
@agent.tool
async def opening_hours(day: str) -> str:
"""Opening hours of the restaurant on a weekday."""
return "12:00 to 22:00"
agent.run(port=8765) # server side: BRISVOX_AGENT_URL=ws://127.0.0.1:8765 Python 3.11 or newer.
TypeScript
import { Agent, s } from "@brisvox/agent";
const agent = new Agent({ name: "luigi", systemPrompt: "You are Luigi's host.", greeting: "Hi, Luigi's here!" });
agent.tool({
name: "opening_hours",
description: "Opening hours of the restaurant on a weekday.",
parameters: s.object({ day: s.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"]) }),
handler: async ({ day }) => (day === "mon" ? "Closed on Monday." : "12:00 to 22:00."),
});
await agent.run({ port: 8765 }); // then: BRISVOX_AGENT_URL=ws://127.0.0.1:8765 Node 20 or newer.
Rust
use std::process::ExitCode;
use std::sync::Arc;
use my_voice_agent::MyTools; // your implementation of the tools API
fn main() -> ExitCode {
// cargo add brisvox --features all-providers
brisvox::run_with_tools(Arc::new(MyTools::default()))
} Tools run inside your own server binary.
Browser
import { BrisvoxCall } from "@brisvox/web";
const call = new BrisvoxCall({
serverUrl: "https://voice.example.com",
// A session token is single use: this is called for every connection attempt.
tokenProvider: async () => (await (await fetch("/api/voice-token", { method: "POST" })).json()).token,
onEvent(event) {
if (event.type === "state") console.log(event.state);
},
}); A dependency-free ES module: WebRTC first, WebSocket fallback on the same port.