Budget controls for AI agents: caps, time budgets and approvals

An agent that can call a model, run a command or send mail needs limits that hold when nobody is watching. Grupr enforces three: a dollar cap on each gateway key, a daily time budget on each agent’s sandbox, and a human approval before anything risky runs. This guide shows what each one does, what the caller sees when it bites, and how to choose the numbers.

The three layers at a glance

Layer 1: dollar caps per key, with overage approvals

In Grupr Analytics an admin issues a virtual key per team, project or tool. Each key carries a monthly cap in US dollars and, optionally, the list of models it may call. Requests through the gateway are priced as they happen and counted against the key.

What the caller sees:

• A request that would take the key past its cap is refused with HTTP 402 and an error of type budget_exceeded. The message tells the caller how to ask for more.
• A call to a model outside the key’s allow-list is refused with HTTP 403 and model_not_allowed.
• If Grupr cannot read the spend ledger, the cap fails closed rather than open.

Asking for more:

• The caller (or an admin in the app) files an overage request for the key: an amount and a reason. One request can be pending per key at a time; a second one is refused with 409.
• A department policy can auto-approve raises up to a set amount, with cumulative headroom, so small overruns do not page anyone.
• Otherwise the request waits for an approver with the admin or finance role, who approves or denies it with a note and an expiry. By default a raise lasts until the end of the month. Approvers are emailed when a request is filed.

This layer exists for organizations running Grupr Analytics. It is enforced at the gateway, so it covers any tool pointed at it, not only Grupr’s own.

Layer 2: a daily sandbox budget per agent

Every Grupr agent has a rented Linux sandbox that keeps its files between calls and pauses when idle, so an idle agent costs nothing. The owner can cap how much of it the agent may use in a day: from 5 minutes to 24 hours per UTC day, set on the agent page.

When the day’s budget is reached:

• The agent’s commands and file operations answer HTTP 429 with code sandbox_budget and a message giving the minutes used and the reset time (00:00 UTC). The agent is told, not silently blocked.
• Scheduled routines that would fire are skipped, with a note in the room saying why.
• The owner gets one room note and one email per day, a “budget reached” item in the agent’s Waiting-on-you list, and the fact shows in the agent’s week summary and the Monday digest.
• The owner’s own “run now” from the agent page is exempt; the budget limits the agent, not the person.

Two related guards run without configuration: a routine that fails three times in a row produces a room note and one owner email, and one that fails twenty times pauses itself until the owner resumes it.

Layer 3: approval before the action

Budgets bound how much; approvals decide whether. In Grupr rooms, every command an agent wants to run in its sandbox posts an approval card to the room and to the owner’s dashboard. The call waits about two minutes for Approve or Deny; a denial returns the reason to the agent. Standing permissions can pre-approve well-understood commands. Sending mail as the agent and installing a routine the agent proposed are approval-gated in the same way.

For coding agents you already run outside Grupr (Claude Code, Codex, Aider, Cursor), Remote Control on the Pro plan routes each permission prompt to your phone, the web, Slack or Discord, requires 2FA on destructive actions, and lets you write allow-list rules so routine prompts stop interrupting you.

Separately, Settings → Budgets in the app holds guidance budgets for your own account: spend estimates reported by Grupr’s review and build tools, with a warning at 80% and an “over” flag at 100%. Grupr Build stops at that cap. These are estimates to steer by, not billing.

A week with the controls on

Illustrative; not a customer’s data.

1. Monday. The platform team’s virtual key (cap $1,500, models limited to two mid-tier options) is at $380. A developer tries a frontier model through it and gets 403 model_not_allowed; the tool falls back to the allowed model.
2. Wednesday. A batch job pushes the key to $1,500 at 14:10. The next call returns 402 budget_exceeded. The job files an overage request for $300 with the reason “re-index after schema change”. The department policy auto-approves raises up to $250, so this one waits; the finance approver approves $300 with a note at 14:25. The raise expires at month end.
3. Thursday. The release agent’s sandbox budget is 60 minutes a day. A flaky test loop burns it by 11:40. The agent’s next command gets 429 with “used 60 of 60 min, until 00:00 UTC”; its 15:00 routine is skipped with a note in the room. The owner sees one note and one email, reads the loop, and raises the budget to 90 minutes.
4. Friday. The agent proposes a new routine to run the suite nightly. The approval card sits in the room until a person approves it; nothing is scheduled before that.

Choosing the numbers

• Key caps: start from last month’s actual for that team and set the cap where an overrun should be noticed, not where it should be impossible. Let the department policy auto-approve the first small raise so a cap is a conversation, not an outage.
• Sandbox budgets: read the agent’s week summary first. One and a half times the average daily sandbox time, rounded up to five minutes, leaves room for normal variance and still catches a runaway loop within the day.
• Approvals: approve by rule what you would approve every time; keep the card for anything that writes outside the workspace, sends mail or costs money.

A read-only report of sandbox time, denials, failures and routine health for one agent is described in Agent usage report in the docs.

What these controls do not do

• There is no per-request dollar cap or token cap on an individual agent’s model calls inside Grupr rooms; the dollar cap is a property of gateway keys in Grupr Analytics.
• The sandbox budget measures time, not money. Grupr plans are flat; the budget protects your attention and the agent’s behaviour, not an invoice.
• Seat-based subscriptions (Claude Max, ChatGPT Team, Cursor Pro) are not reachable by any of these layers.