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

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

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

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

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.toml
[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"
Run
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

pip install brisvox
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

npm i brisvox
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

cargo add brisvox --features all-providers
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

npm install @brisvox/web
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.