Create, validate, and operate the bitrouter.yaml file that controls the local router.

BitRouter can start without a config file. Add bitrouter.yaml when you need explicit providers, stable model names, routing policy, tools, or production settings that should be reviewed as code.

Create a file

bro init
bro config validate -c bitrouter.yaml

The generated file mirrors the zero-config defaults. Delete sections you do not need and keep secrets in environment variables.

server:
  listen: "127.0.0.1:4356"

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

Built-in providers can inherit endpoints, protocols, and model declarations from the bundled registry. Add a custom provider only when the built-in definition does not cover it.

Resolution order

BitRouter uses the first matching source:

Order	Location	Behavior
1	`-c/--config <PATH>`	Explicit; a missing file is an error
2	`./bitrouter.yaml`	Project-local configuration
3	`$BITROUTER_HOME/bitrouter.yaml`	Required when `BITROUTER_HOME` is set
4	`~/.bitrouter/bitrouter.yaml`	Per-user default
5	No file	In-memory zero-config defaults

If BITROUTER_HOME is set but contains no bitrouter.yaml, BitRouter stops instead of silently loading another file.

Secrets and defaults

Use ${NAME} for required environment variables and ${NAME:-default} for an optional fallback:

providers:
  local:
    api_base: "${LOCAL_LLM_URL:-http://127.0.0.1:8000/v1}"
    api_key: "${LOCAL_LLM_KEY}"

Environment references inside YAML comments are ignored. Keep production credentials out of the committed file.

What belongs here

Block	Responsibility
`providers`	Provider endpoints, credentials, accounts, and models
`models`	Named endpoint chains and their fallback order
`presets` / `variants`	Reusable model selectors and routing modifiers
`policy` / `policy_table`	Adaptive and request-shape routing policy
`server` / `upstream` / `database`	Process-facing runtime settings
`mcp` / `mcp_servers` / `server_tools`	MCP aggregation and router-owned tools
`agents`	Local ACP adapter definitions
`plugins`	Guardrails, telemetry, and other plugin configuration

Use Routing for the meaning and precedence of model selectors. Use Self-hosting for networking, authentication, service supervision, and backups.

Editor support

Point a YAML-aware editor at the schema generated from the binary's config types:

# yaml-language-server: $schema=https://raw.githubusercontent.com/bitrouter/bitrouter/main/dist/schema/bitrouter.config.schema.json

Pin main to a release tag when the file must match a deployed binary exactly.

Validate and apply

bro config validate -c bitrouter.yaml
bro route openai:gpt-5 -c bitrouter.yaml
bro reload

config validate checks the file without requiring live provider credentials.
route previews the resolved chain without sending an inference request.
reload applies reloadable changes to the running daemon; restart when the command reports that a changed field is not reloadable.

Treat the generated schema and bro config validate from the version you deploy as the final authority. The exact command flags are in the CLI reference.

Config file