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

Self-Serve from the Dashboard (Pro)

Pro users can configure the daily cap, on-breach action, and routing mode directly from the local dashboard at localhost:4100/dashboard. Open the config tab to see three live controls:

  • Daily spend cap (USD), set or change the hard cap without restarting the proxy.
  • On breach, choose warn, block, or downgrade.
  • Routing mode, switch between auto, complexity, cascade, and passthrough.

Changes persist to ~/.relayplane/config.json and take effect immediately. Free users can still set the cap via the config file or env var below.

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