Quickstart

This page gets BitRouter routing for your agent in under a minute. There are two deployment modes, and three ways to onboard either one — the Agent Skill, the CLI wizard, or manual env keys.

• BitRouter Cloud (default). Hosted endpoint at api.bitrouter.ai. Use BitRouter-hosted models at their token prices with 0% token markup and free routing.
• Local proxy. A single binary on your machine, BYOK with your own provider keys. Basic routing requires no external service.

Both modes use the same open-source routing core (Apache 2.0). The deployment boundary changes, but the client protocol does not, so you can switch modes without rewriting your harness.

Self-host or Cloud?

The routing contract is shared, while operational surfaces follow the deployment boundary:

• Self-host if you already have provider keys, run local/private models, have data-residency rules, or are prototyping solo.
• Cloud if you want BitRouter to operate the router and provide hosted model access.

BitRouter does not package a separate enterprise suite today. Teams with deployment, security, procurement, or support requirements can contact the founders and help shape the team offering.

Do you need your own provider keys? Not for BitRouter-hosted models: one Cloud sign-in covers the managed provider network, model routing is free, and you pay provider token prices with 0% token markup. You can also attach Cloud to a self-hosted binary and use both.

Install the binary

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bitrouter/bitrouter/releases/latest/download/bitrouter-installer.sh | sh

brew install bitrouter/tap/bitrouter

npm install -g bitrouter

cargo install bitrouter

Onboard via the Agent Skill

For agent runtimes that support skills (Claude Code, Cursor, Codex, Copilot, etc.). BitRouter ships a /bitrouter Agent Skill so the agent can install, configure, migrate to, and troubleshoot BitRouter on its own — the skill carries the facts that drift easily (the listen port, env var names, the provider/model slash form, which subcommands exist), and it lives in the main repo at skills/bitrouter/, kept in sync with the code in the same change. Install once:

npx skills add bitrouter/bitrouter    # via the generic skills CLI

Then ask your agent: "Set up BitRouter for me." — the agent runs the wizard, picks Cloud by default, and verifies the connection autonomously.

Onboard via the CLI wizard

For terminal-first setup, launch the wizard:

bro

Bare bro runs a network-free credential probe — BYOK env keys, the cloud session file, and the local credential store — then launches the wizard when nothing is configured. After setup, it opens the configured TUI conversation. The wizard walks three steps:

1. Credentials — sign in to BitRouter Cloud (default), log in to a provider, or paste a BYOK key.
2. Harness — claude or codex, installed via the native installer when missing.
3. Finish — launch the harness, start the proxy at http://127.0.0.1:4356, or exit.

Every step maps to a flag, so an agent (or CI) can run the whole flow without a human. --yes never blocks: it consumes flag-supplied credentials, reports-and-skips anything that would need interactive OAuth, and emits a JSON result envelope on stdout:

bro init --yes --provider openai --provider-api-key "sk-..." --harness claude --after serve
bro init --yes --use-detected --harness claude --after serve   # accept env keys, run proxy
bro init --yes --api-key "brk_..." --after exit                # Cloud key, no launch
bro init --reset                                               # clear credentials, start over

Every flag is documented in the bro init reference. The wizard never writes bitrouter.yaml beyond the canned starter template — your routing config stays yours to edit.

Run self-hosted

Set your provider keys in the environment and start the proxy:

export OPENAI_API_KEY=sk-...    # ANTHROPIC_API_KEY / GEMINI_API_KEY also work
bro start
# Proxy running at http://127.0.0.1:4356

BitRouter auto-detects any key set in the environment — no config file needed. Any provider whose key is present is immediately available. See BYOK for the full list of recognized variables, or local inference to point BitRouter at Ollama, vLLM, or LM Studio for free.

For advanced routing rules, guardrails, or multi-account failover, scaffold a config file:

bro init          # writes ./bitrouter.yaml (override with `-c <path>`)
bro start

Use BitRouter Cloud

Sign in to a BitRouter Cloud account from the terminal — one account covers every model the hosted network offers, with no upstream provider keys required. Hosted model routing is free, and you pay provider token prices with 0% markup:

bro cloud login   # RFC 8628 device flow against api.bitrouter.ai
bro start         # the `bitrouter` provider auto-enables once signed in

Cloud is not a different binary — it's an account you attach. Signing in from a self-hosted binary routes Cloud-managed models alongside your BYOK keys, and you can add or remove the Cloud account at any time without affecting the binary's self-hosted capabilities. You can also point an agent straight at the hosted endpoint without running a local binary at all. See the Supported Models catalog for pricing.

Point your agent at the proxy

However you start it, BitRouter is a drop-in proxy. Point your agent runtime at the proxy base URL — http://127.0.0.1:4356 when self-hosting — and every model call routes through BitRouter with no harness changes.

Verify with a request:

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

Point any OpenAI-compatible runtime at http://127.0.0.1:4356/v1 to route through BitRouter.

Two commands make the routing decision itself legible:

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

Model selectors use two similar-looking forms for different jobs:

Use the slash form by default. Use the colon form only when you intentionally need one configured provider, such as a subscription-backed route. See Model routing for the complete resolution order.

Adaptive routing

Explicit model ids give you deterministic model selection. To let the router apply the policy bound to its auto preset, keep one stable model id in your agent or application:

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

bitrouter/auto requires an auto policy binding and fails visibly when the binding is missing. The dedicated bitrouter/auto guide shows how to create it, inspect the selected route, override one call, learn from runtime adequacy, and explicitly publish a reviewed policy update. Evaluations covers the separate objective-scored evidence path.

Next steps