Budget & Kill Switch

Spend controls, budget limits, forecasting, and emergency stop for AI workloads.

Overview

BrainstormRouter provides budget management and kill switch controls that let operators set spend limits, monitor costs, forecast depletion, and immediately halt all routing in an emergency.

Budget status

Check current spend against limits:

const status = await client.budget.status();

console.log(`Daily spend: $${status.daily.spent_usd}`);
console.log(`Daily limit: $${status.daily.limit_usd}`);
console.log(`Remaining: $${status.daily.remaining_usd}`);

Budget tracking operates at two levels:

Key-level: Each API key can have its own budgetLimitUsd and budgetPeriod
Tenant-level: Daily and monthly limits apply across all keys

Setting budget limits

await client.budget.updateLimits({
  daily_limit_usd: 50,
  monthly_limit_usd: 500,
});

// Clear a limit (return to unlimited)
await client.budget.updateLimits({ daily_limit_usd: null });

Spend forecasting

Project when budgets will be exhausted based on current spend velocity:

const forecast = await client.budget.forecast();

console.log(`Daily projected: $${forecast.daily.projected_usd}`);
console.log(`On track: ${forecast.daily.on_track}`); // true if projected <= limit
if (forecast.daily.depletion_hour) {
  console.log(`Depletes at hour: ${forecast.daily.depletion_hour}`);
}

Kill switch

The kill switch is an emergency stop that suspends routing for the tenant. When activated, all /v1/chat/completions requests return 503 Service Unavailable with X-BR-Kill-Switch: active.

Enforcement is cached in-memory (500ms TTL) and persisted in Postgres via ConfigStore. On read failure, a process that previously observed an active kill switch continues blocking (fail-closed from known-active state). A cold process start during a config-store outage allows traffic until it successfully reads the kill switch state from Postgres.

Activate

const result = await client.killswitch.activate("security incident #123");
console.log(result.active); // true
console.log(result.activated_by); // API key ID

Deactivate

const result = await client.killswitch.deactivate();
console.log(result.active); // false

Check status

const status = await client.killswitch.status();
console.log(`Active: ${status.active}`);
console.log(`History: ${status.history.length} events`);

Exempt endpoints

When the kill switch is active, the following endpoints remain accessible so operators can diagnose and recover:

/v1/killswitch/* — manage the kill switch itself
/v1/budget/* — check spend status
/v1/security/* — security diagnostics
/v1/usage/* — usage data
/v1/models — model listing
/v1/config — configuration
/health — health check

MCP governance tools (br_get_budget_status, br_get_budget_forecast, br_activate_killswitch, br_deactivate_killswitch, br_get_killswitch_status) remain callable through the MCP transport during both kill switch and budget exhaustion. All other MCP tools are blocked. Enforcement happens per-tool-call, not at connection time, so long-lived MCP sessions cannot outlive enforcement.

MCP tools

Both budget and kill switch are available as MCP tools for AI agents:

br_get_budget_status — current spend and limits
br_get_budget_forecast — projected spend and depletion
br_activate_killswitch — emergency stop (requires security.write)
br_deactivate_killswitch — resume routing (requires security.write)
br_get_killswitch_status — current state and history

Python SDK

# Budget
status = client.budget.status()
client.budget.update_limits(daily_limit_usd=50, monthly_limit_usd=500)
client.budget.update_limits(daily_limit_usd=None)  # clear daily limit
forecast = client.budget.forecast()

# Kill switch
client.killswitch.activate(reason="incident")
client.killswitch.deactivate()
status = client.killswitch.status()