Docs

Install tab. Set a cap.

Two minutes with the tab CLI; five by hand with any OpenAI client. Every refusal comes back as an HTTP error with its reason.

What changed lately is in the changelog (feed).

Reference

Self-hosted: Keep provider keys on your machine: tab up, its files, its log.
tab CLI: Every command: what it does, its options, examples.
Troubleshooting: Every refusal and what to do, and the problems people actually hit.
Agent Guard: Stop the tool calls that cannot be undone, before they run: modes, sensitivity, your own rules, held calls.
Billing and plans: What each plan includes, how to start one, add Agents or people, and cancel.
Outside spend and connectors: Read-only bills from the services your agents use: connect them, link them to projects, set alerts.
Single sign-on and SCIM: Sign in through your identity provider (OIDC or SAML) and let it add, suspend and remove people. Fleet.
MCP server: Let Claude Code, Codex, Cursor or claude.ai read your flock and close tabs, as you.

1. Install tab
Node 22 or newer, nothing else. Login is once per machine; the Agent is per folder, kept in .flocktab with no secret in it.
```
npm i -g @hanamorilabs/tab
tab login          # approve this machine in the console
cd my-project
tab claude         # first run asks which Agent this folder runs as
tab codex          # same Agent; any command works: tab <cmd>
```
Keys on your own machine instead of ours: tab up runs the self-hosted proxy (one small binary that ships with tab), then tab login and pick Self-hosted. The ledger and the kill switch stay on flocktab.com.
2. By hand: create a tab, copy the key
Console, New tab. Name the agent. Cap in dollars. Window: day is the default. The key is shown once, prefix ft_live_, hash stored; rotate by issuing a new one.

3. By hand: point the client

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://proxy.flocktab.com/v1",
    api_key=os.environ["FLOCKTAB_KEY"],
    default_headers={
        "x-flocktab-unlock": os.environ["FLOCKTAB_UNLOCK"],
    },
)

4. Handle denials

Body error.code. Header x-flocktab-reason. BLOCKED never reaches the provider.

HTTP	error.code	x-flocktab-reason	When
402	tab_closed	cap.day	Cap or closed tab. Do not retry until it reopens.
402	tool_cap	policy.tool	Named tool hit its cap.
403	risk_blocked	policy.risk	Irreversible. Empty allowlist denies. Remaining floor $25.00.
429	velocity	velocity	Too many calls this minute.
403	model_blocked	policy.models	Model not on the allowlist.
401	key_revoked	-	Unknown or rotated key.
503	ledger_unavailable	ledger	Fail closed. Matching in-flight replay is not a green light.

Do not retry a closed tab until it reopens. 503 is fail closed: do not retry as a green light on a matching in-flight idempotency replay.

Unknown tools are write, not read.

5. Let an agent run the tab
The MCP server gives Claude Code, Codex, Cursor or claude.ai your console: read spend, close a tab, change a cap. OAuth, nothing to paste. Set up the MCP server.
```
claude mcp add --transport http flocktab https://console.flocktab.com/api/mcp
```

Run Claude Code or Codex in a project

Install the harness you use, install tab, and approve this machine with tab login. In the project folder, tab claude or tab codex selects the folder’s Agent on first launch. Confirm the selected Agent and its kind before starting work. Each harness in a project has its own Agent.

npm i -g @hanamorilabs/tab
tab login
cd my-project
tab claude   # Claude Code
# or, for a Codex Agent:
tab codex

For a disposable API Agent, set a cap in the console, run a small task, and verify its ledger entry. Close the tab and confirm the next request is refused. Reopen only after reviewing the reason. See the kill-switch drill for stronger upstream evidence and in-flight behavior.

Test an API-key Agent

An API-key Agent is paid by the flock’s provider key and metered against its cap. Make a small one in an empty folder and run Claude Code on it:

mkdir -p ~/ft-api-test && cd ~/ft-api-test
tab agent create api-test --api --cap 5 --harness claude
tab use        # pick api-test for this folder
tab claude     # say hello

tab status shows the folder running as api-test with its cap, and the console shows the spend. Close the tab in the console and the next message is refused with tab_closed; reopen it and it works again. Lower the cap below one call and the call is refused before the provider.

To test in a folder that already runs as another Agent, run tab use there, pick the API Agent, test, then tab use again and pick the original. Sessions already running keep the Agent they started with; only sessions started in between use the new one. Picking an Agent whose key is already on this machine reuses that key; an Agent keyed on another machine gets a new key, which revokes the one there.

Do not switch the kind of an Agent that has sessions running. tab agent kind moves the Agent for every folder that uses it, and a running subscription session is refused with 403 not_subscription on its next call once the Agent is api.

Supported harnesses

tab sets each harness up in the form it reads, so tab <name> is all you type. Yes means a live run proved it: the call settled on the tab and its tokens matched the vendor’s own count, or, for Agent Guard, a risky call was stopped and an everyday one let through. Coming means built or planned, not yet proven.

Harness	Own key	Flock key	Subscription	Agent Guard
Claude Codetab claude	Yesa direct Anthropic key must be workspace-scoped	Yes	YesClaude Pro or Max	Yes
Codextab codex	Yes	Yes	YesChatGPT plan	Yes
Gemini CLItab gemini	Yes	Yes	Nono plan login	Yes
Antigravitytab agy	Yes	Yes	Nono plan login	Yes
Groktab grok	Yesits own XAI_API_KEY	Yes	YesSuperGrok	Yesfrom tab 0.1.43
Kimi Codetab kimi	Yes	Yes	Cominga Kimi plan with Kimi Code	Yesfrom tab 0.1.43
OpenCodetab opencode	Yes	Yes	Nono plan login	Yes
Goosetab goose	Yes	Yes	Nono plan login	YesmacOS and Linux; Windows isn't covered
Clinetab cline	Yes	Yes	Nono plan login	Yesfrom tab 0.1.43; a held call is refused at once; allow it from the queue and the agent retries
OpenClawtab openclaw	Yes	Yes	Nono plan login	Coming
Pitab pi	Yes	Yes	Nono plan login	Yesfrom tab 0.1.43
Aidertab aider	Yes	Yes	Nono plan login	Nono hook API
Copilot CLItab copilot	Yesits own-key mode, no GitHub models	Yes	Nono plan login	Nono hook API

Tested in live runs on 26 September 2026.

Own key: an API-key Agent keeps the keys the harness already uses (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, ...); tab only moves where they are sent, and every call is held and charged to the tab’s cap. Flock key: a vendor it has no key for uses the flock’s key. Subscription: the harness’s own plan login, recorded at list price and never charged to the tab. A model named vendor/model goes to OpenRouter, and with no Anthropic key, Anthropic models go through OpenRouter too.

Editors are set up once, by hand, with the tab’s key and the proxy as an OpenAI-compatible endpoint (/v1, or /v1/openrouter for vendor/model ids):

VS Code Copilot agent mode: Chat: Manage Language Models, Add Models, custom endpoint. It runs on your machine, so a local proxy works.
Cline extension: API Provider OpenAI Compatible, base URL, the tab key, a model id.
Cursor: Settings, Models, API Keys, OpenAI key and Override OpenAI Base URL. Cursor sends these calls from its own servers, so it needs the hosted proxy (https://proxy.flocktab.com), not a local one. Tab completion stays on Cursor.

Not yet: Cursor’s command-line agent has no model endpoint setting, and Devin runs entirely in its own cloud; record their spend as outside spend.

Use your own subscription login

Choose a subscription Agent when creating it, sign in through the harness, and launch it with tab. The proxy passes that login to the vendor and records usage under the account the vendor identifies. Account and plan discovery comes from the vendor; you do not need to declare them.

The tab’s kill switch and supported policies still apply. List-price activity is not charged to the tab balance and does not replace the vendor’s quota. Use the subscription pool guide and keep usage valuations separate from invoices.

Attribute costs to a project

In the console, select the project that owns the work and check which named Agents belong to it.
Connect the relevant vendor in Outside spend. Confirm the reporting period, currency, and whether the amount is billed usage or an estimate.
Assign a known resource, such as an OpenRouter key, to its project. Assign an entire account only if all the represented usage has that owner.
Reconcile the attributed components and unresolved remainder to the account total. Keep subscription list-price activity separate from charges.

Follow the worked OpenRouter example and weekly review template. Project reporting does not create a shared enforced project cap; admission is controlled by each Agent’s tab.

1. Install tab

2. By hand: create a tab, copy the key