# Tokens and the runner BakedBrie has two kinds of keys an agent cares about: - **API token**: what your MCP client (Claude Code, Codex) sends to BakedBrie. It acts as the person who minted it. - **Runner key**: what `bakedbrie-runner` on the user's computer uses to take cards and run them with the user's own Claude Code or Codex. Both are minted by a person in the BakedBrie web app. An agent cannot mint, list or revoke tokens: those routes need a signed-in browser session and answer `INTERACTIVE_SESSION_REQUIRED` to a token. ## Mint an API token The user does this, in a browser: 1. Open `https://app.bakedbrie.com`, pick the workspace, then go to **Settings**, **Apps and API** (the page is `/w//settings/api-tokens`). 2. Under **Tokens**, enter a token name the user will recognize, for example `Claude Code on my laptop`. 3. Choose what the token can do (see presets below). 4. Click **Create token**. BakedBrie asks for the user's password and authenticator code. 5. Copy the token from **Copy your token now**. This is the only time it is shown. 6. Put it in the `BAKEDBRIE_TOKEN` environment variable, not in a file or chat. Then follow [Connect Claude Code](/docs/connect-claude-code) or [Connect Codex](/docs/connect-codex). Facts about tokens: - A token looks like `bbk_prd_<12 characters>_<43 characters>`. Send it as `Authorization: Bearer `. - A token belongs to one workspace. It acts as the member who minted it, on the boards that member can open, with that member's role. - Tokens expire after 90 days. - The **Tokens** list shows each token's name, preset, last use and expiry. **Revoke** stops a token right away. ### Presets | Preset | `whoami` shows | What it can do | |---|---|---| | Full control | `full_control` | Anything the minting member can do in the app, on the boards they can open. The default. | | Read only | `read_only` | Reads boards, cards, results and receipts, and can preview moves. Every change is refused with `TOKEN_READ_ONLY`. | | Runner | `runner` | Only for `bakedbrie-runner`. It takes cards for the user's computer and sends back results, nothing else. Every other route answers `TOKEN_RUNNER_ONLY`. | A Custom preset (pick exactly what the token can do) is shown as coming later. Tokens minted before presets existed are Full control. A preset never widens later: a Read only token stays read only even if features are turned off and on. ### Check what your token is Call `whoami`. The `token` field has `id`, `label` and `preset`. The `capabilities` field says which features are on. See [whoami](/docs/reference/tools/whoami). ### What is not a token - The MCP server does not use OAuth. If your client offers an MCP sign-in, skip it and use the bearer token. - A browser session cookie and a bearer token together are refused with `AMBIGUOUS_AUTHORITY`. ## The runner The runner runs cards on the user's own computer with the Claude Code or Codex they already use, signed in to their own Claude or ChatGPT plan. BakedBrie never receives that sign-in. The runner exists only while the `runner` capability is on for the workspace. Check `whoami`: `capabilities.runner` must be `true`, and `capabilities.runner_claude` or `capabilities.runner_codex` says which program BakedBrie accepts. While it is off, creating a runner key is refused with `CAPABILITY_OFF`, and a running runner waits and asks again every 5 minutes. ### Step 1: create a runner key The user does this, in a browser: 1. Go to **Settings**, **AI accounts** (`/w//settings/connections/ai`), and open the section **Your Claude or ChatGPT plan on your computer**. 2. Click **Create a runner key**, give it a name (for example `My laptop`), and confirm with password and authenticator code. 3. Copy the key from **Copy your runner key now**. It is shown once. It will be pasted into `bakedbrie-runner pair`, never into a file or chat. A runner key is an API token with the Runner preset. You can also mint one on the Apps and API page by choosing the Runner preset. ### Step 2: install and pair On the user's computer, in a terminal. Needs Node.js 18.20 or later, and `claude` (2.1.280 or later) or `codex` (codex-cli 0.155.1 or later) signed in to the user's plan. ```bash npm install -g https://app.bakedbrie.com/runner/bakedbrie-runner.tgz bakedbrie-runner pair ``` `pair` asks for the runner key with hidden input. For scripts, `bakedbrie-runner pair --token-stdin` reads it from stdin. Never pass the key as a command line argument. The key is saved in `~/.bakedbrie/runner.json` (only the user can read it). ### Step 3: keep it running ```bash bakedbrie-runner ``` Cards run while this is open. Ctrl-C stops it. Other commands: `bakedbrie-runner status`, `bakedbrie-runner unpair`, `bakedbrie-runner --version`. After the first start, the computer shows up under **Your computers** in Settings, AI accounts, and in `whoami` under `runners`. ### Step 4: use it for cards When the runner says hello, BakedBrie creates a runner AI account for each program that passed its checks, for example "Claude Code on My laptop". Then: 1. Call `list_ai_accounts` ([reference](/docs/reference/tools/list_ai_accounts)). A runner account has `kind: runner`, says whether its computer is online, and whose cards it runs. 2. With the user's yes, bind it with `bind_ai_account` ([reference](/docs/reference/tools/bind_ai_account)) for the workspace, one board, or one agent. 3. If you bound it to an agent, publish the agent again with `publish_agent` so the new version uses it. The owner chooses who can run cards on their computer: **Only me** (default) or **Anyone on the board**. Only the owner of that computer can change it, in Settings, AI accounts. There is no MCP tool for it. ### What the runner refuses The runner checks each program before each run. A program signed in with an API key instead of a plan is refused (`RUNTIME_API_BILLING`) unless the runner was started with `--allow-api-billing`. Signed out is `RUNTIME_SIGNED_OUT`, too old is `RUNTIME_OUTDATED`. These show on the card. The full list is in [Refusals: runner](/docs/refusals#runner-key-and-run-codes). ### Disconnect In Settings, AI accounts, **Disconnect** stops that computer taking cards right away. Boards and agents set to use it wait until another AI account is chosen. To connect again, create a new runner key and pair. ## Next step [Concepts](/docs/concepts) explains AI accounts, bindings and capabilities.