Quickstart

Install

pip install breakerbox

Start from a template

Zero-to-guarded fast — scaffold a spec plus ready-to-run guarded Python for a common pattern:

breakerbox init --list                      # see the templates
breakerbox init --template research-agent   # writes research-agent.spec.json + research-agent.py

Each template comes with budgets, a velocity limit, and side-effect tags already wired:

Fill in the node bodies in the generated .py and run it — guard() is already wired. Prefer a canvas? Open the visual builder instead.

Guard a workflow

guard() wraps your compiled LangGraph app and enforces a dollar budget across the whole run, including any sub-agents.

from breakerbox import guard

# my_app is your compiled LangGraph app
app = guard(my_app, budget_usd=5.00)

result = app.invoke({"messages": [...]})

That's it — the workflow now can't spend more than $5.00. Breakerbox meters tokens itself (tiktoken, then reconciles against the provider's reported usage) so the number is honest.

How the budget works

Each hop reserves its estimated cost against the remaining budget, executes, then reconciles the escrow against actual usage — the same shape as a credit-card hold. Sub-agents draw from the parent's remaining budget, so the cap is hierarchical, never per-call.

When the budget trips

Breakerbox trips at hop boundaries, never mid-call, so no request is interrupted:

• pause — checkpoints the run so you can resume it later with more budget.
• kill — stops the run and finalizes the receipt, listing any side-effecting tools that fired.

Private runs (optional cloud dashboard)

To see runs in the dashboard, create a key under Settings → Your ingest key and set it where your agents run:

export BREAKERBOX_INGEST_KEY="abk_…"   # runs become private to your account

Next

• The visual builder
• Receipts
• Security model