Field notes · 2026-10-05 · RunVouch

Set a hard budget per scheduled agent run (Anthropic, OpenAI, OpenRouter)

Provider spend limits are monthly and account-wide. How to cap one scheduled agent run and one day, and pause the agent before the next run starts.

I ran agents and a crypto trading bot unattended for two years. The trading bot had a position limit from day one, because everybody knows a bot can lose money. The agents had no such limit for a long time. They only called an API, and the spend limit in the provider console felt like enough. It is not enough, and the reason is simple: that limit is the wrong size and the wrong period for a job that runs at 03:00 every night.

This article is about the gap between a monthly account limit and a budget for one scheduled run, and how to close it on Anthropic, OpenAI and OpenRouter.

RunVouch is a watchdog for unattended AI agents: a dead man's switch, a cost cap and an outcome check for jobs that run while nobody is looking.

Why a provider spend limit is not an AI agent budget per run

I read the current docs of all three providers before writing this. Here is what each limit really covers.

Anthropic. Spend limits are monthly. Each usage tier has a monthly cap, you can set your own lower limit for the organization or for a workspace, and when you reach a limit you set yourself, requests return HTTP 400 until access resumes. Source: Anthropic rate limits and spend limits.
OpenAI. Spend limits are monthly, per organization or per project. Enforced as a hard limit, requests fail with a 429 and the code project_spend_limit_exceeded. The docs add that enforcement is not instantaneous, so recorded spend can slightly exceed the configured amount. Source: OpenAI spend limits.
OpenRouter. The finest grain of the three. A key can carry its own credit limit, with an optional limit_reset that the docs show as daily at midnight UTC, and an exhausted key gets a 402. Sources: OpenRouter limits and provisioning API keys.

None of these knows what a run is. A month is the unit for two of them, a day per key is the best case for the third. A nightly job that normally costs 40 cents can cost 30 dollars a night for a week and stay under every one of these limits. And when a monthly limit does trip, it trips for everything behind that workspace, project or key, including the jobs that behaved.

Gateway caps vs watchdog caps

A gateway cap sits in the request path. The provider limits above are gateway caps, and so is the limit on an OpenRouter key. The strength is that it is truly hard: the request is refused. The weakness is that it only sees requests. It does not know which agent sent them, whether this is the first run today or the ninth, or whether the job produced anything.

A watchdog cap sits next to the job. It knows the agent by name, it knows where a run starts and ends, and it adds up cost per run and per day. The weakness is the mirror image: it is not in the request path, so it cannot refuse a single API call. What it can do is refuse the next run.

I use both, each for what it is good at. The gateway limit is the ceiling for the whole account. The watchdog cap is the budget for one agent.

How to set a hard budget per scheduled agent run

Step 1. Cap the run from the inside where the runtime allows it. For headless Claude Code this exists. The CLI reference lists --max-budget-usd, the maximum dollar amount to spend on API calls before stopping, and --max-turns. Both are print mode only, and spend from subagents counts toward the budget.

claude -p --max-budget-usd 2.00 --max-turns 40 "write the nightly report"

Step 2. Give the agent a per-run and a per-day cap in the watchdog.

rv agent nightly-report --cadence 24h --cap-run-cost 2 --cap-day-cost 10 --evidence

Step 3. Wrap the scheduled command.

0 3 * * * rv run nightly-report --evidence-file out.html -- ./nightly.sh

Step 4. Make sure the cost is reported. A cap on a number nobody reports is decoration. I learned this on my own jobs: they reported 0.00 on 3733 runs while five of them were paying for Claude calls. With the Claude Code plugin, tokens and cost come from the transcript through hooks. Any other job, on OpenAI or OpenRouter or anything else, prints one line with what it spent and rv run picks it up:

echo "RUNVOUCH_COST=0.82"

Step 5. Send the alert somewhere you read. Telegram, Slack or a webhook. A run over its cap raises BUDGET_RUN, a day over its cap raises BUDGET_DAY.

Per-run cap or per-day cap: which one stops runaway agent cost

They catch different failures, so set both.

The per-run cap catches the single run that goes wrong: a loop, a context that keeps growing, a tool that is called again and again. For that last case there is a separate detector as well, RETRY_STORM, which fires when the same tool is called with identical input eight times or more.

The per-day cap catches the failure the per-run cap cannot see: many runs that are each fine. A cron line that fires every minute instead of every day. A retry wrapper that restarts a failing job forever. Forty runs of 30 cents each never cross a 2 dollar run cap, and they cross a 10 dollar day cap before lunch.

Set the run cap at a few times the normal cost of a run, not at the normal cost. Agent runs vary. For slow creep under the cap there is DRIFT, which compares a run with the last seven using the median absolute deviation.

What happens when the cap is crossed: pause, not kill

A crossed cost cap pauses the agent. The next rv run is refused, the command is not started, and the message says how to resume:

rv agent nightly-report --resume

It never kills a running process. That is a choice. A watchdog that kills a job halfway through a database migration or a git push causes a worse incident than the bill it was trying to prevent. The honest consequence: the run that crosses the cap finishes, and you pay for that one. That is why step 1 matters where it is available, and why the cap bounds the damage to one run instead of a week of nights.

The pause is also the only case in which RunVouch stops your command. The client fails open: if the API is down, times out or returns an error, the job runs as if there were no watchdog.

FAQ

Can RunVouch stop a run in the middle when it goes over budget?

No. It alerts, pauses the agent and refuses the next run. To stop spending inside a run, use a limit in the runtime, such as --max-budget-usd for claude -p, or a limited key at the gateway.

Does this work if my job does not use the rv client?

Presence and failure do: every agent has a ping URL (/ping/<token>, with /start, /fail or the exit code), so anything that can call a URL can report. Cost caps need a cost, which comes from rv run, the Claude Code plugin, the MCP server or the Python and Node clients.

What does it cost?

Three agents are free. Solo is $9 a month, Team is $29. The server is MIT licensed and can be self-hosted, and the hosted version runs in the EU.

Related field notes

Try it: free for 3 agents · Docs: Claude Code · cron