Budget Caps

Stop runaway AI agent spend before it happens. Set a daily cap and let RelayPlane handle the rest.

What Budget Caps Do

AI agents can rack up hundreds of dollars in API costs in a single session. A bug in a loop, an unexpected context explosion, or a forgotten background process can drain your budget overnight. RelayPlane's budget cap feature tracks spend in real time and enforces a daily spending limit — automatically downgrading models or pausing sessions before costs spiral out of control.

Setting dailyCapUSD

Add dailyCapUSD to your RelayPlane config file to enable budget enforcement:

1// relayplane.config.js
2module.exports = {
3  dailyCapUSD: 10,        // hard daily spending limit in USD
4  capAction: 'downgrade', // 'downgrade' | 'pause' | 'block'
5};

Or set it inline when starting the proxy:

1RELAYPLANE_DAILY_CAP_USD=10 npx relayplane start

Verifying Your Budget

Use the relayplane budget command to check current spend against your daily cap:

1$ relayplane budget
2
3Budget Status (today)
4─────────────────────────────────
5Daily cap:    $10.00
6Spent so far: $3.42
7Remaining:    $6.58
8Reset at:     00:00 UTC
9
10Breakdown by model:
11  claude-opus-4-7        $2.10
12  claude-sonnet-4-6      $1.02
13  claude-haiku-4-5       $0.30

What Happens When the Cap Triggers

When the daily cap is reached, RelayPlane applies your configured capAction:

downgrade (default)

Requests are automatically routed to a cheaper fallback model. For example, Opus → Sonnet → Haiku. Agents keep running but at reduced cost. The model downgrade ladder is applied progressively until spend stays within budget.

pause

New requests return a 429 Budget Cap Reached error. In-flight requests complete. The session is paused until you manually resume or the cap resets at midnight UTC.

block

All requests are immediately blocked with a 429 response. Use this for strict enforcement where any overage is unacceptable.

The model downgrade ladder applies only to models from the same provider. Cross-provider downgrade is not supported in Phase 1.

Viewing Session History

Use relayplane sessions to see cost history by session:

1$ relayplane sessions
2
3Recent Sessions
4──────────────────────────────────────────────────────
5SESSION ID        AGENT        STARTED      COST    STATUS
6sess_a1b2c3       claude-code  10:42 UTC    $1.23   complete
7sess_d4e5f6       aider        09:15 UTC    $0.87   complete
8sess_g7h8i9       cursor       08:01 UTC    $4.12   capped → downgraded
9sess_j0k1l2       claude-code  yesterday    $2.45   complete
10
11Run `relayplane sessions --id sess_g7h8i9` for full breakdown.

Sessions marked capped → downgraded hit the daily cap mid-session and had their model downgraded automatically.

Next Steps