Router policy

A router policy is the complete desired-state contract for a BitRouter deployment. It covers every reviewed setting that determines how the router is exposed, where it can send work, how it selects and executes routes, which constraints it enforces, and what evidence it records.

bitrouter.yaml is the main operator-authored expression of that policy. The term is intentionally broader than the file's policies, policy, or policy_table fields: those are specific mechanisms inside the overall router policy.

BitRouter can start from in-memory defaults, but a file makes the intended behavior reviewable, reproducible, and deployable as code.

Policy artifacts

Keep bitrouter.yaml and any linked policy lock in version control. Keep credential values in your secret store and reference them from the policy.

Policy layers

The policy file is an assembly point, not the place to learn every subsystem. Each layer has an owning guide:

This page explains how those layers form one policy. Follow the owning guide when you need the schema and behavior of a specific block.

Create a policy file

bro init
bro config validate -c bitrouter.yaml

The generated file mirrors the zero-config defaults. Delete sections you do not need, make intentional behavior explicit, 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.

Find the active policy

BitRouter uses the first matching source:

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. The resolved value participates in the running policy, but the secret itself should not be committed.

Validate the contract

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. Then validate both syntax and route behavior:

bro config validate -c bitrouter.yaml
bro route bitrouter/auto -c bitrouter.yaml
bro policy check -c bitrouter.yaml

• config validate checks the complete router policy without requiring live provider credentials.
• route previews model resolution without sending an inference request.
• policy check cross-validates the policy file and its linked routing-policy lock.

Apply and review changes

bro reload -c bitrouter.yaml
bro policy status -c bitrouter.yaml
bro status -c bitrouter.yaml

reload applies reloadable changes while the daemon is running. Restart for process-bound changes when the command reports that a field cannot be reloaded. For production rollout, validate and preview the policy with the same released binary that will serve it.

The review loop is:

1. Author the desired behavior.
2. Validate the file and linked artifacts.
3. Preview important model routes.
4. Apply the policy to the running router.
5. Inspect telemetry and evaluate outcomes.
6. Review and commit any intentional policy change.

Runtime evidence may justify a candidate, but it does not silently become policy. Publishing a routing-policy change remains an explicit, digest-checked operation.

Three meanings of policy

BitRouter uses narrower policy terms within the broader router policy:

bro policy init, check, compile, and publish operate on routing policy. bro policy create creates an access-control policy file. Both are components of the router policy, but they are not interchangeable.