Onboarding

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. No upstream keys to manage; agent-native x402/MPP pay-per-use, or BYOK on top.
• Local proxy. A single binary on your machine, BYOK with your own provider keys. Zero infrastructure dependencies.

Both modes run the same open-source core (Apache 2.0) — the routing engine is identical, so you can start in one mode and switch later without touching your harness.

Self-host or Cloud?

Every core capability works the same either way — Cloud only adds what needs a server you don't run.

• Self-host if you already have provider keys, run local/private models, have data-residency rules, or are prototyping solo.
• Cloud if you want no key management and per-request billing, a managed provider network without provider signups, team workspaces, or an uptime SLA.

Do you need your own provider keys? Only if you self-host with BYOK — a Cloud account needs no upstream keys: one sign-in covers the whole hosted network, billed per request, failed requests not charged. You can also attach Cloud to a self-hosted binary and use both.

Install the binary

<Tabs items={['macOS / Linux', 'Homebrew', 'npm', 'cargo']}>

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:

bitrouter skills add bitrouter        # via BitRouter's own installer
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:

bitrouter

Bare bitrouter 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, or prints a one-line status when it is. It never re-onboards a configured user and never silently spawns a daemon. 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:

bitrouter init --yes \
  --provider openai --provider-api-key "sk-..." \
  --harness claude --after serve

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

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
bitrouter 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 & private models to point BitRouter at Ollama, vLLM, or LM Studio for free.

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

bitrouter init          # writes ./bitrouter.yaml (override with `-c <path>`)
bitrouter 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:

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

You can also point an agent straight at the hosted endpoint without running a local binary. Either way the core is the same — a Cloud account is an account and network, not a separate deployment. See the Supported Models catalog for pricing.

Attach Cloud to a self-hosted binary

Cloud is not a different binary — it's an account you attach:

bitrouter cloud login
# Opens a browser to sign in and pick a workspace.
# Your local binary now routes Cloud-managed models alongside your BYOK keys.

You can add or remove the Cloud account at any time. The binary's self-hosted capabilities are unaffected either way.

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.

Next steps