# Bitrouter Pi

> Use this skill when driving pi-agent with the BitRouter provider — choosing local vs cloud target, configuring env vars, obtaining keys, and troubleshooting model discovery. Trigger when the user mentions the BitRouter pi package, BITROUTER_TARGET, BITROUTER_API_KEY, brvk_ keys, or wants to point pi at a local BitRouter daemon or BitRouter Cloud.

- Skill: `bitrouter/bitrouter-pi` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bitrouter/bitrouter-pi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bitrouter/bitrouter-pi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: Apache-2.0
- Author: bitrouter (https://skillmd.com/u/bitrouter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bitrouter/bitrouter-pi

---


# BitRouter Provider for pi-agent

The `@bitrouter/pi` package registers a `bitrouter` provider in pi-agent.
Models are **discovered dynamically** at startup via `GET ${baseUrl}/v1/models`
— there is no hard-coded model list to maintain.

## 1. Pick a target

Set `BITROUTER_TARGET` before launching pi:

| Value | Base URL (default) | When to use |
|---|---|---|
| `local` (default) | `http://127.0.0.1:4356/v1` | Local BitRouter daemon (BYOK) |
| `cloud` | `https://api.bitrouter.ai/v1` | BitRouter Cloud (managed, no per-provider keys) |

Override the URL for either mode with `BITROUTER_BASE_URL`:

```bash
BITROUTER_BASE_URL=http://192.168.1.10:4356/v1 pi ...
```

## 2. Authentication

### Local target

The local daemon defaults to `skip_auth: true` (loopback requests admitted
with no key). If auth is enabled, mint a `brvk_` virtual key:

```bash
bitrouter key sign --user <id>
# → brvk_...
export BITROUTER_API_KEY=brvk_...
```

If `BITROUTER_API_KEY` is unset and `skip_auth` is true, the provider works
with no key at all.

### Cloud target

No `BITROUTER_API_KEY` env var is used for cloud. The extension reads the
BitRouter daemon's credential file written by `bitrouter auth login`:

- Linux/macOS: `$XDG_DATA_HOME/bitrouter/account-credentials.json`
  (falls back to `$HOME/.local/share/bitrouter/account-credentials.json`)
- Windows: `%LOCALAPPDATA%\bitrouter\data\account-credentials.json`

If the file is missing or the `access_token` has expired, the provider is
**not registered** and an error is logged. Fix: run `bitrouter auth login`.

## 3. Model discovery

On startup the extension calls `GET ${baseUrl}/models` and maps each entry
to pi's Model shape (id, name, reasoning, input modalities, contextWindow,
maxTokens, cost). If the endpoint is unreachable or returns zero models, the
provider is not registered — check that the daemon is running and that
`BITROUTER_BASE_URL` points at the correct host.

## 4. MCP

MCP is **not bundled** in this package. BitRouter itself is an MCP gateway
(`/mcp` routes in `bitrouter.yaml`). Use `bitrouter mcp serve` to expose
upstream MCP servers through the daemon, then configure pi's MCP client to
point at it.

## 5. Quick reference

```bash
# Local — no key (skip_auth default)
BITROUTER_TARGET=local pi ...

# Local — with a brvk_ key
BITROUTER_TARGET=local BITROUTER_API_KEY=brvk_... pi ...

# Cloud — credentials from bitrouter auth login
bitrouter auth login          # one-time; persists credential file
BITROUTER_TARGET=cloud pi ...

# Override base URL
BITROUTER_BASE_URL=https://my.proxy/v1 BITROUTER_TARGET=cloud pi ...
```

## 6. Troubleshooting

| Symptom | Fix |
|---|---|
| `cloud auth unavailable: … expired` | `bitrouter auth login` |
| `no BitRouter cloud credentials` | `bitrouter auth login` |
| `no models discovered` | Daemon not running or wrong URL — check `bitrouter status` and `BITROUTER_BASE_URL` |
| Model discovery fails with `HTTP 401` | Set `BITROUTER_API_KEY=brvk_...` or enable `skip_auth` in `bitrouter.yaml` |