From zero to a metered, capped AI budget in a few minutes.
TokenBrake Server runs on your own machine or a small box you control. Three ways, fastest first.
Downloads a single zero-dependency file (needs Node 24+) and prints your key + start command:
curl -fsSL https://tokenbrake.com/install.sh | sh
Prefer to grab the file yourself? Download tokenbrake-server.mjs and run TB_KEY=your-secret node tokenbrake-server.mjs. That's the whole server — one file, nothing to install.
docker run -d --name tokenbrake \ -p 8788:8788 \ -e TB_KEY=pick-a-long-secret \ -v tokenbrake-data:/data \ akkad/tokenbrake
TB_KEY=pick-a-long-secret node server/app.mjs
Always set TB_KEY before exposing the server. It's the shared secret every request must present. Without it, anyone who can reach the server can use it.
Open http://localhost:8788/ for the live dashboard.
TokenBrake is a drop-in proxy. Change one line — your provider base URL — and add your TokenBrake key. Your provider API key still passes straight through and is never stored.
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8788/openai/v1",
api_key="sk-...your real key...",
default_headers={
"x-tokenbrake-key": "pick-a-long-secret",
"x-tokenbrake-agent": "support-bot", # label this stream
},
)
from anthropic import Anthropic
client = Anthropic(
base_url="http://localhost:8788/anthropic",
api_key="sk-ant-...your real key...",
default_headers={
"x-tokenbrake-key": "pick-a-long-secret",
"x-tokenbrake-agent": "content-gen",
},
)
What's an "agent"? The x-tokenbrake-agent header labels each stream of usage — a bot, a script, a project. That's what a "seat" counts. Any device (laptop, server, phone) that can set these headers is metered the same way.
Give each agent a monthly budget and a mode, from the dashboard or the API:
curl -X POST http://localhost:8788/api/budget \
-H "x-tokenbrake-key: pick-a-long-secret" \
-H "content-type: application/json" \
-d '{"name":"support-bot","budget":200,"mode":"hard"}'
You decide when to be told. Don't want a peep until you're at 125%? Set it. Add a webhook (Slack, your own endpoint) and TokenBrake posts to it when a threshold is crossed.
curl -X POST http://localhost:8788/api/alerts \
-H "x-tokenbrake-key: pick-a-long-secret" \
-H "content-type: application/json" \
-d '{"name":"support-bot","thresholds":[1.25],"webhook":"https://hooks.slack.com/…"}'
Leave the webhook blank to stay silent. Thresholds are fractions of budget: 1.0 = 100%, 1.25 = 125%.
After you buy a license, set the key and restart. Solo covers up to 3 agents; Business is unlimited. Enforcement is soft — going over your plan never stops your traffic, it just prompts an upgrade.
TB_KEY=pick-a-long-secret \ TB_LICENSE=TB-... your license key ... \ node server/app.mjs
Your AI agent can operate TokenBrake on its own — check the meter, set a budget, turn the cap off or on, set alert thresholds. Two ways:
Any HTTP-capable agent: it reads a machine-readable manifest and discovers every action.
curl http://localhost:8788/agent.json
MCP-aware tools (Claude Desktop, Cursor, and others): add the bundled MCP server so TokenBrake shows up as native tools. Zero dependencies — it just calls your server.
// in your tool's MCP config
{
"tokenbrake": {
"command": "node",
"args": ["/path/to/tokenbrake/server/mcp.mjs"],
"env": { "TB_URL": "http://localhost:8788", "TB_KEY": "pick-a-long-secret" }
}
}
Then "check my TokenBrake meter" or "turn the cap off for the support bot" just works. Every write still requires TB_KEY.
TokenBrake meters OpenAI, Anthropic, xAI (Grok), Groq, DeepSeek, Mistral, and Google Gemini — including streaming and prompt caching. Most are OpenAI-compatible (point the OpenAI SDK at the matching path); Gemini uses Google's own format, so point the Google GenAI SDK's base URL at …/gemini.
| Provider | Base URL to use |
|---|---|
| OpenAI | …/openai/v1 |
| Anthropic | …/anthropic |
| xAI / Grok | …/xai/v1 or …/grok/v1 |
| Groq | …/groq/v1 |
| DeepSeek | …/deepseek/v1 |
| Mistral | …/mistral/v1 |
| Google Gemini | …/gemini (Google GenAI SDK) |
| OpenRouter | …/openrouter/v1 (hundreds of models) |
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8788/groq/v1", # or /xai, /deepseek, /mistral
api_key="...your real provider key...",
default_headers={
"x-tokenbrake-key": "pick-a-long-secret",
"x-tokenbrake-agent": "grok-bot",
},
)
Plus OpenRouter as an aggregator — one key, hundreds of models, all metered. More native providers (Azure OpenAI, Bedrock) are on the roadmap. Need one? Email us and it moves up the list.
Pricing is estimated from provider-published rates and rounds up when uncertain, so a cap can't be quietly slipped. It's a safety brake, not a billing system of record — always keep provider-side limits on too.
Lost your license key? Go back to the checkout and re-enter your original payment transaction hash. Keys are generated from your payment, so the same transaction always returns the same key.
Renewal. Licenses are annual. When one expires, the server keeps running (soft enforcement) and prompts you to renew. Renew any time by buying again; if you gave an email at checkout, we'll send a reminder.