/bitrouter

name: bitrouter
description: >
  Use when installing, configuring, running, or troubleshooting BitRouter from
  its CLI — a self-hosted LLM proxy on 127.0.0.1:4356 routing OpenAI- or
  Anthropic-shaped traffic to any provider, via a coding-agent subscription,
  hosted BitRouter, or your own keys. Covers bro init, provider
  credentials, starting the default ACP TUI with bro, routing, and spend.
  Trigger on bitrouter.yaml, port 4356, brk_ keys, "replace litellm", or
  pointing a coding agent at a proxy.
license: Apache-2.0
metadata:
  author: BitRouterAI
  tags: [llm, proxy, routing, cli, ai-gateway, claude-code, codex]

BitRouter

BitRouter is a self-hosted Rust daemon at `http://127.0.0.1:4356` that routes OpenAI- or Anthropic-shaped requests to providers selected in §4.

Activate in one pass

Work top to bottom, probing before asking.

1. Probe

bro --version          # not found -> step 2
bro status             # liveness + `spend`; `running: false` when nothing is reachable
bro providers list     # ID  MODELS  ACTIVE  API_BASE

These emit JSON by default (`--human` is readable). Branch on the result: missing command → §2; no active providers → §3; stopped daemon → `start`; both ready → §5.

2. Install

curl --proto '=https' --tlsv1.2 -LsSf https://bitrouter.ai/install.sh | sh

macOS: `brew install bitrouter/tap/bitrouter`. Node: `npm install -g bitrouter`. Windows: `powershell -ExecutionPolicy Bypass -c "irm https://bitrouter.ai/install.ps1 | iex"`. Verify with `bro --version`; on failure read `references/diagnose.md`.

3. Configure

A human runs `bro` to complete onboarding using searchable Up/Down lists of registry providers (including BitRouter Cloud), ACP harnesses and actions. After setup the same command opens the saved default ACP TUI. Credentials alone do not mark setup complete. For scripted setup:

bro init --yes --use-detected --harness codex --after exit

This saves `chat.agent: codex-acp` in the resolved config, or the BitRouter home when no config exists. `--model ID` persists the default model too. Existing settings are preserved; `--force` resets them. Read `providers_skipped_interactive` in the JSON report for logins needing a human. No hand-written provider or agent entry is needed for Codex or Claude ACP. See `references/cli.md` for flags, config precedence and first-run defaults.

4. Choose providers — subscription first

These logins are interactive, so they are what `providers_skipped_interactive` reports. Work the order below: it buys the same tokens for less money.

**a. The subscription they already pay for.** If the user drives Claude Code or Codex, log that in first so the harness keeps serving its own models from the plan they have already bought instead of from metered API calls.

bro providers login claude-code    # adopts the live Claude Code session
bro providers login openai-codex   # ChatGPT PKCE flow in a browser
bro providers login bitrouter      # hosted; same sign-in as `cloud login`

Auth is catalog-derived; `references/providers.md` lists each login method.

**b. Hosted BitRouter for everything else.** Signing in adds a managed `bitrouter` provider to this daemon; it is not a second deployment.

**c. BYOK for anything they want to own directly.** Export the key and start — the daemon auto-enables every provider whose key is present, and `export ...; bro reload` rotates one without a restart.

Detected vars: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` (not `GOOGLE_API_KEY`), `OPENROUTER_API_KEY`, `OPENCODE_ZEN_API_KEY` (zen *and* go).

`providers login` also takes `--api-key` / `--key-stdin`, and `references/cloud-setup.md` covers the hosted account, credits, and `brk_*` keys. Net effect: the subscription serves its native models; hosted BitRouter or BYOK supplements everything it does not cover.

5. Start the desired agent interface

BitRouter's full-screen conversation uses temporary operational inspectors:

bro code                    # conversation with Choose agent picker
bro code codex              # explicit interactive ACP session
bro run claude "summarize this repo"  # headless ACP turn

Both built-in adapters require Node.js 22+ and `npx`; a compatible local CLI is selected automatically behind the pinned adapter. For the harness's own native interface, use the reversible per-process launcher:

bro claude
bro codex -- --search

`launch <agent>` accepts catalog native harnesses; `claude`, `claude-code`, and `codex` are shortcuts. Everything after `--` is forwarded verbatim, and user configuration is not edited.

Leave the harness's own model on its subscription and let BitRouter carry the rest — subagents, bulk work, models the plan does not include. Pinning the whole harness off a subscription they already pay for usually costs more, so make it a deliberate choice rather than a default.

**The restart handoff — say it every time.** Existing harness processes cannot be rerouted. End with: "run `bro claude` (or restart the harness with the env override) to route this session." MCP is control/introspection only; inference goes to the daemon HTTP API.

For an ACP client, use `bro acp serve claude` or `bro acp serve codex`. Stable ACP v1 on exact adapter pins, initializing the harness with the client's capabilities and transparently carrying multiple harness-native sessions on one connection. Native IDs and history remain harness-owned; `acp_recording.enabled` optionally records the observable ACP transcript locally; `acp checkpoints` freezes and annotates it. Route leases (`_bitrouter/route/list|set|reset`) and session-attributed cost are capability-gated and need a local control binding, which an explicit remote `--base-url` does not provide. Read `references/sessions.md` — the pins and the wire contract are there — before reasoning about this surface.

6. Verify

bro route claude-sonnet-4-6   # preview; check `polic