Resolve a model selector into an ordered provider chain, define fallback, and inspect the result.

Routing turns the request's model into an ordered chain of concrete provider endpoints. Most workflows need only a direct selector or a named fallback chain.

Model selector forms

The separator carries routing meaning:

Form	Meaning	Example
`provider/model`	A stable logical model id from the registry; every eligible provider that declares it can join the route	`anthropic/claude-opus-4.8`
`provider:model`	A direct local route through one configured provider	`anthropic:anthropic/claude-opus-4.8`

Prefer the slash form in application code. Use the colon form when the provider itself is part of the decision, such as a subscription-backed account or a specific custom endpoint.

Resolution order

BitRouter resolves a request in four stages:

Apply a known @preset and optional :variant.
Treat provider:model as an explicit provider route.
Resolve a matching entry under models as a virtual model.
Otherwise, build a cascade from active providers that declare the bare model.

Subscription-backed providers are explicit-route-only. A bare model never silently consumes a personal Claude or Codex subscription.

Selector	Use it for
`openai:openai/gpt-5.4`	Pin one provider and logical model
`openai/gpt-5.4`	Route a logical model through eligible providers
`coding`	Use a named chain from `models`
`@fast`	Apply a reusable preset
`@fast:cost`	Apply a preset, then a known variant
`bitrouter/auto`	Use the routing policy bound to the `auto` preset

For a bare model, BitRouter filters active providers by only, ignore, required tags, capabilities, and protocol compatibility. It then orders candidates by explicit provider priority or the registry's provider-class priority, followed by provider ID.

Presets and variants accept three sort values:

Value	alpha.31 behavior
`alphabetical`	Provider priority, then provider ID
`cost`	Accepted, but currently uses the same deterministic fallback order
`latency`	Accepted, but currently uses the same deterministic fallback order

Cost- and latency-based live scoring are not active in alpha.31. Do not describe :cost or :latency as measured optimization until a release provides the corresponding metrics-backed recommender.

Use routing.only, routing.ignore, or provider priority when the order must be explicit today.

Fallback

Define an ordered chain with a virtual model:

models:
  coding:
    strategy: priority
    endpoints:
      - provider: openai
        service_id: gpt-5
      - provider: anthropic
        service_id: claude-sonnet-4-6

A request for coding tries endpoints in YAML order. BitRouter advances after retryable upstream failures: 5xx, 408, 429, transport or timeout failures, invalid upstream responses, and exhausted provider credit. Other client-side 4xx errors fail immediately.

Use strategy: cascade only when the endpoints are interchangeable and routing preferences may reorder or filter them. In alpha.31, cost and latency sorts still use the deterministic priority/provider-ID fallback described above.

Presets

Presets put model substitution, prompt defaults, parameters, policy binding, and routing filters behind a short name:

presets:
  fast:
    model: coding
    system_prompt: "Be concise."
    params:
      temperature: 0.2
    routing:
      only: [openai, anthropic]

Call it as @fast. Request fields win over preset defaults, so a preset provides a stable baseline without taking control away from the caller.

bitrouter/auto is the public spelling of the auto preset and requires that preset to be bound to a routing policy. Create the binding with bro policy init rather than hand-authoring a partial lock file.

Variants

A variant changes routing preferences only:

variants:
  private:
    routing:
      require_tags: [private]
  primary:
    routing:
      only: [openai]

Append a known variant to a model or preset, such as coding:private or @fast:primary. An unknown suffix is not removed; it remains part of the model selector.

Variants do not grant access, bypass guardrails, or change virtual-key policy.

Request capabilities

Structured outputs and other request capabilities filter the route to compatible provider/model targets before execution. See Structured outputs for the cross-protocol request shapes.

Inspect and verify

bro config validate -c bitrouter.yaml
bro models --provider openai
bro route coding -c bitrouter.yaml
bro route @fast:primary -c bitrouter.yaml

bro route uses the running daemon when available and otherwise resolves from the selected config file. It is the authoritative way to review the chain before sending traffic.

Routing