/bitrouter

name: bitrouter
description: >
  Use this skill when the user wants to install, configure, run, or
  troubleshoot BitRouter — an LLM proxy that runs two ways: a local Rust
  daemon at http://localhost:4356 (BYOK) or BitRouter Cloud at
  https://api.bitrouter.ai/v1 (managed, brk_* keys, Stripe credits or
  x402 wallet). Unifies OpenAI, Anthropic, Google, OpenRouter, GitHub
  Copilot, and OpenCode Zen/Go behind one endpoint. Also covers signup
  on bitrouter.ai, minting brk_ API keys, running auditable benchmarks,
  migrating off LiteLLM /
  OpenRouter / any OpenAI- or Anthropic-compatible gateway, editing
  bitrouter.yaml, and wiring coding-agent harnesses (Claude Code, Codex,
  Hermes Agent, Harbor Terminus-2, OpenClaw), plus optimizing agent workflows
  against eval quality and normalized routed cost. Trigger on "set up a local LLM proxy",
  "managed AI gateway", "replace litellm", "point claude code at a
  proxy", "bitrouter cloud", "brk_ key", anything naming bitrouter.yaml,
  port 4356, Harbor Terminus-2, or api.bitrouter.ai — even when the user does not name
  BitRouter directly.
license: Apache-2.0
metadata:
  author: BitRouterAI
  tags:
    - llm
    - proxy
    - routing
    - openai
    - anthropic
    - google
    - gemini
    - openrouter
    - copilot
    - opencode
    - ai-gateway
    - claude-code
    - codex

BitRouter

BitRouter routes OpenAI- or Anthropic-shaped requests to any LLM provider. It runs **two ways**: a local Rust daemon at `http://127.0.0.1:4356` (BYOK — your keys, your machine) or a managed cloud service at `https://api.bitrouter.ai/v1` (one bill, no per-provider keys).

1. Ask first: Local or Cloud?

Before touching anything, ask the user this:

> Do you want to run BitRouter **locally** (install the daemon, BYOK with your own provider API keys, you pay each upstream directly) or use **BitRouter Cloud** (managed proxy at `api.bitrouter.ai`, one bill via Stripe credits or x402 wallet payments, no per-provider keys needed)?

If Local

Continue to §2 (Install). Skip the Cloud paths below.

If Cloud — four entry points

Each is written up in full (dashboard URLs, credit model, key rotation) in `references/cloud-setup.md`, keyed A-D.

1. **Web playground** (A) — zero install. <https://bitrouter.ai> → sign up → top up credits → use the in-browser playground. 2. **`brk_*` API key in their SDK** (B) — the production path. Mint at Dashboard → API Keys, then point any OpenAI- or Anthropic-shaped SDK at `https://api.bitrouter.ai/v1` (drop `/v1` for the Anthropic SDK). No daemon. 3. **Permissionless wallet** (C) — Solana/EVM, no account; x402/MPP handles payment. Point the user at the docs; do not script the JWT signing yourself. 4. **Headless CLI** (D) — `bitrouter cloud login`, RFC 8628 device flow. The credential persists and auto-refreshes, and the local daemon then auto-adds a `bitrouter` provider in zero-config mode, so entitled models are routable as `bitrouter:<model-id>` against `localhost:4356` — no `brk_*` paste, no config edit. An explicit `BITROUTER_API_KEY` overrides that stored session for inference; unset it to use the login credential. `bitrouter cloud --help` drives the management surface (keys / usage / billing / policy / budget / preset / byok).

2. Install (Local only)

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

macOS users may prefer `brew install bitrouter/tap/bitrouter`; environments that already manage global npm tools can use `npm install -g bitrouter`. Windows:

powershell -ExecutionPolicy Bypass -c "irm https://bitrouter.ai/install.ps1 | iex"

`https://bitrouter.ai/install.{sh,ps1}` is the canonical entry point — it proxies the latest GitHub release's cargo-dist installer and survives transient asset-publishing gaps by falling back to the most recent release that actually has the installer attached.

Verify: `bitrouter --version`. If `command not found`, see `references/diagnose.md`.

3. Run (Local only)

**Guided onboarding.** Bare `bitrouter` is the front door: a network-free credential probe launches the wizard when nothing is configured, or prints a one-line status plus a `bitrouter launch` hint when it already is. It never re-onboards and never auto-spawns. `bitrouter init` re-runs it; `--yes` runs it headlessly and scaffolds the starter `bitrouter.yaml`. Every prompt has a flag equivalent — see `references/cli.md` → *Setup helpers*. The two commands below remain the fast path.

**Zero-config (BYOK).** Export any of the supported env vars and start the daemon. It auto-enables every provider whose key is present.

export OPENAI_API_KEY=sk-...           # openai
export ANTHROPIC_API_KEY=sk-ant-...    # anthropic
export GEMINI_API_KEY=...              # google  (NOT GOOGLE_API_KEY)
export OPENROUTER_API_KEY=sk-or-...    # openrouter
export OPENCODE_ZEN_API_KEY=...        # opencode-zen AND opencode-go (shared)

bitrouter start          # detached daemon, logs to ~/.bitrouter/bitrouter.log
bitrouter status         # green dot + pid / listen / model count
bitrouter update         # self-update the binary (prereleases by default); --check to dry-run

The daemon writes its runtime files (`bitrouter.sock`, `bitrouter.pid`, `bitrouter.log`, optional `bitrouter.db`) into `~/.bitrouter/`.

Beyond the local-login providers, the daemon merges the public provider registry on startup: any registry **BYOK** provider whose key is present (convention `${NAME}_API_KEY`) becomes routable for the models it serves — the curated catalog plus any BYOK / BYO-subscription extras the provider lists beyond it — and providers are ranked by a configurable priority ladder. See `references/providers.md` → *Provider registry*.

**With a config file.** When you want explicit control (multi-account, MCP servers, ACP agents, custom providers):

bitrouter init                    # writes ./bitrouter.yaml (skip_auth: true)
$EDITOR bitrouter.yaml
bitrouter config va