Set Up Routing

This page gets model routing working end to end. It assumes you've installed BitRouter and have the proxy running (bitrouter start, listening at http://127.0.0.1:4356). Everything here is the act step of the loop — the walkthrough is opinionated; the full reference lives in Models & Routing.

Zero-config: keys in the environment

With no config file at all, BitRouter auto-enables any provider whose key is set:

export OPENAI_API_KEY=sk-...        # ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY also work
bitrouter start

Point your runtime at http://127.0.0.1:4356/v1 and request any model those providers serve — BitRouter picks a provider for you. For anything beyond that, scaffold a config:

bitrouter init        # writes ./bitrouter.yaml
bitrouter config validate

BitRouter looks for bitrouter.yaml in the current directory first, then $BITROUTER_HOME, then ~/.bitrouter — and falls back to zero-config when none exists.

Declare providers

providers:
  openai: {}                                  # uses OPENAI_API_KEY
  anthropic:
    api_key: "${ANTHROPIC_KEY_A}"             # ${VAR} resolved at load time
  google:
    accounts:                                 # multi-account failover
      - { api_key: "${GEMINI_KEY_A}", label: primary }
      - { api_key: "${GEMINI_KEY_B}", label: overflow }
    account_strategy: failover                # or balance
inherit_defaults: true

inherit_defaults: true keeps the built-in provider catalog; your blocks override per provider. Rate limits, custom api_base endpoints, per-model pricing, and protocol mappings all live under the same providers.<id> key — see Provider selection for the full field reference and how providers behind a model get ranked.

Route by name: presets and variants

A preset is a named routing profile your agent selects in the model field:

presets:
  coding:
    model: anthropic/claude-opus-4.8
    routing:
      require_tags: [tools]

curl http://127.0.0.1:4356/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "@coding", "messages": [{"role": "user", "content": "Hello"}]}'

@coding:cheap selects a variant — the same preset with a different provider preference. Presets are also the opt-in boundary for adaptive routing: binding a policy: to a preset is what lets the loop learn on it. See Presets and Model variants.

Add a fallback chain

A virtual model walks an ordered endpoint list when an upstream fails — a retryable failure (5xx / 408 / 429 / timeout / credit exhaustion) advances to the next endpoint:

models:
  assistant:
    strategy: priority          # or cascade
    endpoints:
      - { provider: anthropic, service_id: claude-opus-4.8 }
      - { provider: openai, service_id: gpt-5.5 }

Your agent requests assistant; the chain is invisible to it. See Model fallback for strategy semantics and per-endpoint overrides.

Verify

bitrouter models                 # every model id routable right now
bitrouter route anthropic/claude-opus-4.8   # preview the routing decision

Then send a real request and watch it route — wire up tracing first if you want to see every hop.

Next steps