/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, MCP configuration, local skill directories, native BRO tasks, ACP harnesses, 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. Native CLI tasks use bounded read workers and database execution records; see `references/cli.md` for permissions and restart limitations. Enabled tenancy uses startup-only `tenancy.capacity` budgets independent of stored tenant/key counts; see `references/remote-administration.md`. Metered `google` uses Chat Completions with `GEMINI_API_KEY`; native Gemini routes, `google-ai` and Vertex Express are retired.

`bro task managed` submits to the local daemon, which owns native tools/Core and the existing durable journal. Use `--request-id` for exact retries, `managed-status` for passive inspection, `managed-cancel` with the original boot/input key for cancellation, and `managed-answer` for explicit MCP skill consent; continuation requires confirmed release. Custom durable harness clients use the negotiated managed-core HTTP/WebSocket profile; see `references/managed-core.md` for binding, ACKs, results and current limits.

For a stopped local SQLite DB, `bro tenancy offline snapshot/inventory/verify` produces DB-only evidence. Snapshot `--format v2` and an explicit private `--scratch-directory` process complete history with finite working memory; v1 remains the default. `offline restore` copies verified evidence into a new database path and preserves identity; normal startup and external recovery remain required. `offline audit` serves protected receipt reads. `offline upgrade-capacity` records only a verified legacy count-latch upgrade. See `references/cli.md` for identity, replay, resource-budget and writer-fence requirements.

Activate in one pass

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

Official macOS distributions support Apple Silicon (`arm64`) only. macOS (Apple Silicon): `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

Bare `bro` ensures a ready background daemon and returns to the shell. Router config or detected credentials suffice; a verified running target needs neither current client credentials nor YAML. No chat agent is required. Missing setup needs stdin/stderr terminals. Menus use number/name or keyword + Enter; Enter accepts the shown default. Secrets are hidden; EOF/Ctrl-C cancels. Scripted setup:

bro init --yes --use-detected --after exit
bro                         # ensure readiness; idempotent on repeat

Optional `--harness codex|claude` saves `chat.agent`; `--model` saves the model. Optional MCP setup uses `--mcp-name NAME --mcp-from FILE`. Router progress survives resource failures. Install skills separately with `npx skills`; onboarding has no installer. Settings survive; `--force` resets them. `init --yes` saves/exits; `--after serve` waits for readiness; `--after launch` invokes the selected native tool. Read `providers_skipped_interactive`; `agents_selected` is selection evidence, while deprecated `harnesses_installed` stays empty. Saves are `saved_only`; daemon `config_state` reports reload/restart needs. Missing non-TTY setup and readiness timeouts fail. See `references/cli.md` for output/cancellation.

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 models from the plan they already bought.

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`; `references/cloud-setup.md` covers hosted accounts, credits, and `brk_*` keys. Hosted BitRouter or BYOK supplements subscriptions.

5. Start the desired agent interface

Use single-operation CLI controls or the harness's own native interface. Observing state never submits, approve