Budget & Safety¶

A squad budget pauses a run before it uses more tokens or time than you allow. A budget is off until you turn it on, and each of its limits is off until you set it.

Turning a Budget On¶

Open the budget from the squad page's ⋯ menu, or with Set limits on the budget meter. A new squad has no budget: the setup wizard sets none, and the meter says Off.

1. Turn on the Budget switch at the top. With no limit set yet, the budget only tracks usage.
2. Each limit reads No limit. Set a limit turns that one limit on at its recommended value, and the slider then adjusts it. Remove limit turns it off again.

Only the limits you set apply; every other limit stays off. Each change is saved as you make it, and Done closes the dialog. Turning the switch off keeps the values you set, so turning it back on restores them.

A budget applies to runs submitted while it is on. A running run that has a budget re-reads the saved one before each task, so a raised limit, a removed one, or the switch turned off reaches it before its next task. A run submitted while the budget was off stays without one.

How Tokens Are Counted¶

Every model round of a task counts its reply, plus how much its prompt grew since the round before. The first round counts its whole prompt. A tool loop sends the whole conversation again every round, so counting each round's full prompt would count the start of the conversation once per round.

For example, a task whose first prompt is 6,000 tokens runs 10 tool rounds and a final answer. Each round replies with 1,500 tokens, and its tool result adds 3,000. The budget counts 6,000 + 11 × 1,500 + 10 × 4,500 = 67,500 tokens: the last prompt plus every reply. The model server processed 330,000 prompt and completion tokens for the same task, which is what the squad's analytics report.

The same count applies to the per-task, per-agent, and per-run limits, to the planner's call, and to the usage a container-mode agent's runner reports when its container finishes. The bundled agent runner counts Anthropic cache writes and cache reads as prompt tokens. A custom image that reports no usage is not held to token limits: its task still runs, and the run log says that token limits did not apply to it. A remote agent's model calls run on its own node and are not counted here.

Token Limits¶

Plan Limits¶

Time Limits¶

Where the Recommended Values Come From¶

The recommended values leave room for a normal run on a local model, so turning a limit on does not stop work that would otherwise finish:

• Tokens per task: a normal task as above counts 67,500 tokens. A task that fills a 128K context window, with eleven 4,000-token replies, counts about 175,000. Both fit in 200,000.
• Tokens per agent: a 20-task plan split over three workers gives one agent seven tasks, about 470,000 tokens. 1,000,000 is about twice that.
• Tokens per run: 20 normal tasks and the planner come to about 1,380,000 tokens. 3,000,000 is about twice that.
• Default task time limit: at about a minute per model call, a normal task takes eleven minutes. 30 minutes is about three times that.
• Run time limit: tasks run one at a time, so 20 normal tasks take about three and a half hours. 6 hours leaves room for slower tasks.

Per-Agent Time Limits¶

Each squad agent has two time limits of its own under Settings in its configuration, next to Max Tool Rounds and Max Tokens. They apply whether or not the squad's budget is on.

The two limits measure different things. A task makes several model calls with tool calls in between, so the LLM response time limit is what decides whether one long call, such as a large file written in a single tool call on a slow local model, can finish. The task time limit bounds the whole task, and because it is checked only between model responses, it cannot cut a call that is still running.

A remote agent (one added from a registered remote profile) shows only the task time limit: its model calls run on the remote node, under that node's own settings.

Defaults by where the model runs¶

An agent that sets no limits of its own gets defaults from where its model runs. The agent's settings show the default for its model under each row, and Use default returns a changed LLM response time limit to it.

A model counts as hosted only when the agent's model was picked from that provider in the model list. A model with no provider recorded, such as one loaded here or the Settings > Models default, counts as one you run. Without its own Max Tokens, a task also asks for no more than a quarter of the model's context window, so the prompt and the task's tool rounds keep the rest: 2,048 tokens on an 8K window, 4,096 on 16K, and 8,192 on 32K or more for a model you run.

A local model generates 10 to 50 tokens per second, so 540s, the most the router allows, covers one long reply such as a large file written in a single tool call.

The router's time limit¶

A squad task's model call goes through the app's router, which has its own time limit for a request that is not streamed (timeouts.request.standard.total, 300s as shipped; see Request Timeouts and Health Checks). When an agent's LLM response time limit is longer, which includes the 540s default of an agent on a model you run, the run raises the router's limit for that agent's model before its first task, as a per-model override in the router configuration, so the router does not end the call first. The override only ever raises the router's limit, and it is written again on each run, so a router settings save that drops it is repaired by the next run.

The maximum of 540s is the most the bundled router accepts for that limit. A model on another machine in a cluster is reached through that machine's router as well, which keeps its own time limit; raise it there if the remote model needs longer.

Warning Threshold¶

The Warning at setting (default 80%) emits one squad:budget-warning per run when the counted tokens reach that percentage of Tokens per run, or the running time reaches it of Run time limit. It is shown only while one of those two limits is set, since it measures nothing else. The notification says which of the two it is.

Real-Time Budget Tracking¶

The Budget Meter on the squad's overview shows the current run against the limits that are set:

• Counted tokens, against Tokens per run when it is set
• Running time against Run time limit, when it is set. The clock holds while the run is paused
• Tasks in the plan against Tasks per plan, when it is set

A squad whose budget is off shows Off on the meter, with Set limits.

The meter's token figure is lower than Tokens processed in the squad's analytics and on the agent cards, which count the conversation again on every round. The ? beside the meter's token row says so.

Safety Events¶

Budget Warning¶

When counted tokens or running time reach the warning threshold, a squad:budget-warning event is emitted and the budget meter turns amber.

When a Limit Is Reached¶

When a token or time limit is reached, the run pauses:

• The running task stops after its current model response and is recorded as stopped by that limit. This includes the final answer an agent gives once its tool-call rounds run out. A container task is checked when its container finishes
• No new task starts
• squad:execution-paused and squad:budget-exceeded are emitted. The event names the limit (limit), the task it stopped (taskId), and its agent (agentId), and its reason gives the figures
• The run card shows which limit it was, the task, and the fix, and the notification says the run is paused

Resume puts the stopped task back in the queue, so its dependents still run. Before the task runs again, the run checks its limit once more:

• A per-task limit that is still at or below the value that stopped the task pauses the run again, without starting the task. Raise the limit or remove it, then resume. To run the task again at the same limit, use Retry this task, which retries it and resumes the run.
• A run-wide limit is checked before every task. A run that is still over one pauses again.
• To let the run finish without the stopped task, Skip it while the run is paused. Its dependents are skipped too.

Recorded usage at or above 10,000,000 tokens is already at the largest limit a budget accepts, so raising a limit cannot resume the run; skip its remaining tasks to let it finish, or cancel it.

The task-count and re-plan limits also refuse actions: the planner cannot create more tasks, an approval with too many tasks is refused, and a rejection past the re-plan limit is refused while the plan stays awaiting approval.

Emergency Stop¶

An emergency stop is operator-initiated: use Emergency Stop on the budget meter, POST /api/v1/squads/{id}/emergency-stop, or aigo squad emergency-stop. It stops every running execution of the squad at once:

• Running tasks are aborted immediately, and a container task's container is stopped. A tool call that was still running when the stop landed may already have taken effect. When the task runs in the app rather than in a container, that call is recorded as a failed call whose error says it was abandoned, so the possible side effect stays visible on the audit log's Tool executions tab and in the run's events
• Pending tasks are cancelled
• Each execution's status changes to failed, recorded as stopped by the emergency stop rather than by a budget limit, and Rerun failed tasks can start its unfinished work again
• A squad:emergency-stopped event is emitted with the reason

Settings That Were Removed¶

Concurrent agents and Agent idle timeout are no longer offered. A run dispatches its tasks one at a time, so at most one agent of a run works at once and no concurrency value could bind, and nothing measured an agent's idle time. A budget saved with either keeps the value, which has no effect.

Best Practices¶

• Start from the recommended values: Set a limit starts each limit where a normal run fits. Lower a limit after watching a few runs on the budget meter, not before.

• Use per-agent limits: If one agent tends to be verbose, set a lower per-agent token limit rather than raising the total budget.

• Set task time limits: A task time limit catches a stuck agent before it consumes the entire budget. Give an agent that does long work, such as installing packages, its own longer limit instead of raising the default for every agent.

• Give slow models more time per response, not per task: A local model already gets 540s, the most the router allows. If one response still runs out, lower that agent's Max Tokens or load the model with a smaller context, rather than raising its task time limit. A cloud model that needs longer can have its LLM response time limit raised up to 540s.