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:

Open https://app.bakedbrie.com, pick the workspace, then go to Settings, Apps and API (the page is /w/<workspace>/settings/api-tokens).
Under Tokens, enter a token name the user will recognize, for example Claude Code on my laptop.
Choose what the token can do (see presets below).
Click Create token. BakedBrie asks for the user's password and authenticator code.
Copy the token from Copy your token now. This is the only time it is shown.
Put it in the BAKEDBRIE_TOKEN environment variable, not in a file or chat. Then follow Connect Claude Code or Connect Codex.

Facts about tokens:

A token looks like bbk_prd_<12 characters>_<43 characters>. Send it as Authorization: Bearer <token>.
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.

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:

Go to Settings, AI accounts (/w/<workspace>/settings/connections/ai), and open the section Your Claude or ChatGPT plan on your computer.
Click Create a runner key, give it a name (for example My laptop), and confirm with password and authenticator code.
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.

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

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:

Call list_ai_accounts (reference). A runner account has kind: runner, says whether its computer is online, and whose cards it runs.
With the user's yes, bind it with bind_ai_account (reference) for the workspace, one board, or one agent.
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.

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 explains AI accounts, bindings and capabilities.