Init and config
bro command reference for init and config.
BitRouter ships as one static binary, bro, with no runtime dependencies to install. It runs the local router your applications call, launches supported coding agents, and exposes scriptable commands for routing, evaluation, optimization, and your hosted account.
Start with bro init for guided setup, bro serve for a foreground router, or bro code for BitRouter's coding conversation.
Every command below is generated from the binary's own --help, so the flags you see here are the flags your installed version accepts.
Conventions
- Output is JSON by default for scriptable commands. The compatibility options
--json,--human, and--context <NAME>go before the command when needed. -c/--config <PATH>overrides config discovery for any command that loads a config. Discovery order:./bitrouter.yaml→$BITROUTER_HOME/bitrouter.yaml→~/.bitrouter/bitrouter.yaml→ zero-config (in-memory defaults, auto-enabling providers from env keys).- Credentials live under
$XDG_DATA_HOME/bitrouter/account-credentials.json(mode0600), written bycloud loginorproviders login.
Environment variables
| Variable | Effect |
|---|---|
OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, OPENCODE_ZEN_API_KEY | Zero-config BYOK — auto-enables the provider. See BYOK |
BITROUTER_API_KEY | Cloud API key; enables the managed bitrouter provider |
BITROUTER_HOME | Config discovery override (see above) |
BITROUTER_OAUTH_AS | Override the OAuth authorization server for self-hosted Cloud |
OTEL_EXPORTER_OTLP_ENDPOINT | Opt in to OTLP export. See OpenTelemetry |
BitRouter discovers its config in this order — first hit wins:
./bitrouter.yamlin the current directory$BITROUTER_HOME/bitrouter.yaml(must exist when the variable is set)~/.bitrouter/bitrouter.yaml- Zero-config — in-memory defaults, auto-enabling any provider whose API key is set in the environment
Any command taking -c/--config overrides discovery. The daemon chdirs into the config's directory on startup, so relative paths (database.url, policy.path) resolve there. A JSON Schema for the config lives at dist/schema/bitrouter.config.schema.json in the repo for IDE autocomplete.
The full onboarding walkthrough — wizard steps, headless flags, recipes — is the Quickstart.
bro init
Guided onboarding wizard that sequences credential, harness, and finish steps to first value. Interactive by default; --yes (or no TTY) runs it headlessly, emitting the JSON result envelope and never blocking on a human. Every prompt has a flag equivalent (below) so an agent can drive the whole thing. Saves the default ACP harness and optional model in the resolved config or BitRouter home; --force resets existing settings
Usage: bro init [OPTIONS]
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Configuration to create/update; defaults to the resolved config or BitRouter home |
-y, --yes | Run non-interactively: process the flags below, never block, emit the JSON envelope, and scaffold the starter config |
--force | Allow overwriting an existing bitrouter.yaml when scaffolding |
--reset | Clear stored onboarding credentials (cloud session always; provider credentials after a confirm, or unconditionally under --yes) before running |
--cloud-login | (Step 1) Sign in to BitRouter Cloud via device-flow OAuth. Skipped and reported under --yes (a machine can't complete the device flow) |
--api-key <BRK_KEY> | (Step 1) Seed the cloud credential from a brk_ API key (non-interactive) |
--provider <ID> | (Step 1) Log in to an upstream provider by id (repeatable). A paired --provider-api-key seeds it non-interactively; otherwise it is reported-and-skipped under --yes |
--provider-api-key <KEY> | (Step 1) API key for the --provider at the same position (repeatable) |
--use-detected | (Step 1) Accept the auto-detected credential(s) without prompting |
--harness <HARNESSES> | (Step 2) Built-in ACP harness: claude or codex (first is the default) Possible values: |
- claude: Anthropic's Claude Code CLI (claude) | |
- codex: | OpenAI's Codex CLI (codex) |
--after <AFTER> | (Step 3) What to do at the end: launch | serve | exit Possible values: |
- launch: Open BitRouter's TUI using the selected ACP harness | |
- serve: | Start the daemon and print a paste-in snippet for an existing tool |
- exit: | Do nothing further |
--model <ID> | (Step 3) Default daemon-routable model, saved for subsequent TUI sessions |
Re-runs the wizard interactively; with --yes it never blocks and emits a JSON result envelope — the form an agent or CI should drive. Refuses to overwrite an existing bitrouter.yaml unless --force.
bro init --yes --use-detected --harness claude --after servebro config
Configuration tooling (validation against the published schema)
Usage: bro config <COMMAND>
bro config validate
Validate a config file: structure, provider derives resolution, and upstream-URL (SSRF) safety. Exits non-zero on an invalid config — safe to run in CI. Unset ${VAR} references are substituted with a placeholder and reported as warnings, so secrets need not be present
Usage: bro config validate [OPTIONS]
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml / bitrouter.json. When omitted, the standard resolution chain applies (./bitrouter.yaml → $BITROUTER_HOME → ~/.bitrouter) |
The CI-safe check: exits non-zero when the config doesn't match the schema.
bro config validate -c ./bitrouter.yamlHow is this guide?