OAuth Pool Setup

Kanna’s OAuth pool holds one or more Claude OAuth tokens. Kanna picks one per chat, spreads load across them, and falls over automatically when one hits a rate limit.

Why a pool

• Runs on your Claude plan — Kanna passes your OAuth token to the Claude Agent SDK rather than an API key.
• Rate-limit fallover — a limited token is set aside with its reset time and the next turn picks another.
• Per-token labels and concurrency — tag tokens (personal, work-1) and set how many chats each may serve at once.

Add a token

1. Open Settings → Providers
2. Under Claude OAuth tokens, click Add
3. Paste a Claude OAuth token (from claude /login on a machine where the CLI is interactive)
4. Give it a label
5. Save

That is the whole setup — there is no driver flag or env var to set afterwards.

More than one token

Adding a second token is worth it once you regularly run several chats at once, or hit limits mid-session. Kanna always picks the eligible token with the fewest current holders, so load spreads before it stacks.

Each token has an optional max concurrent chats (default 1). Raise it when you have more concurrent chats than tokens and rate limits are not what is stopping you.

Where tokens are stored

In ~/.kanna/data/settings.json, mode 0600, alongside the rest of your settings. Treat that file as a secret in any backup. See OAuth Pool Admin for the on-disk shape, the status values, and what to do when a token stops being picked.