Limits & Enforcement

The three limit types

Every Nanny execution is governed by three independent limits. Any one of them can stop a run.

Timeout

The wall-clock time limit in milliseconds. The moment the child process has been running for timeout ms, Nanny kills it — regardless of what it’s doing.

[limits]
timeout = 30000   # 30 seconds

Timeout enforcement requires no instrumentation — it works for any process in any language.

Steps

The maximum number of agent steps allowed. Requires #[nanny::tool] (Rust) or @tool (Python) to report tool calls.

[limits]
steps = 100

Tokens

The maximum number of tokens the agent may spend. Each tool declares its token cost per call; Nanny tracks the running total and stops the moment the budget is exhausted.

[limits]
tokens = 1000

Named limit sets

In a multi-agent system, each agent has a different risk profile. The analysis agent makes expensive API calls — it deserves a tight token ceiling. The reporter just writes a file — it barely needs a budget at all. Named limit sets let each role get exactly the ceiling it deserves, configured once in nanny.toml.

[limits]
# Global ceiling — applies to any run not using a named set
steps   = 200
tokens  = 500
timeout = 120000

[limits.ingestion]
steps   = 20
tokens  = 50
timeout = 30000

[limits.analysis]
steps   = 60
tokens  = 200    # tighter — this agent makes expensive calls
timeout = 60000

[limits.visualization]
steps   = 20
tokens  = 100
timeout = 30000

[limits.reporter]
steps   = 20
tokens  = 50     # loose — this agent just writes a file
timeout = 30000

Named sets inherit from [limits] and override only the fields you declare. In the example above, [limits.ingestion] inherits from the global [limits] and overrides all three fields. A set that only declares timeout would inherit steps and tokens from the base. Each agent activates its own set via the @agent("role") decorator:

@agent("analysis")
def run_analysis(path: str): ...    # governed by [limits.analysis]

@agent("reporter")
def run_reporter(output: str): ...  # governed by [limits.reporter]

Or activate a named set from the CLI for the entire run:

nanny run --limits=analysis

This is easy to misread, so it’s worth being explicit: entering [limits.analysis] does not give the analysis role its own fresh 200-token pool. There is exactly one running total for tokens spent (and steps taken) in a given run, for its entire lifetime. A named set only changes which ceiling that same total is compared against while the set is active. Concretely: if [limits.ingestion] already spent 40 of its own 50-token ceiling before handing off to [limits.analysis] (tokens = 200), the analysis phase starts with only 160 tokens of real headroom left, not a fresh 200. If the run had already spent close to 200 tokens by the time [limits.reporter] (tokens = 50) becomes active, the very next governed call in that phase can fail immediately, even though the reporter itself hasn’t done anything yet. Size named-set ceilings with this in mind: later scopes in a pipeline need ceilings large enough to absorb everything earlier scopes may have already spent, not just their own expected usage in isolation. If your process runs multiple, logically independent phases and you want each one to start from a genuinely clean budget, unrelated to what came before, that’s a different thing: a new run, not a new named set. See fresh_run() in the Python or Rust SDK guide for how to do that.

What happens when a limit is hit

Nanny kills the child process immediately — no grace period, no way for the agent to catch or delay the stop.
An ExecutionStopped event is emitted with the reason.
A human-readable message is printed to stderr: nanny: stopped — TimeoutExpired.
Nanny exits with code 1.

The stop reasons are:

Reason	Trigger
`AgentCompleted`	Process exited cleanly on its own
`TimeoutExpired`	Wall-clock timeout exceeded
`MaxStepsReached`	Step limit hit
`BudgetExhausted`	Token budget exhausted
`ToolDenied`	Tool not in allowlist
`RuleDenied`	Custom rule returned denial
`ManualStop`	Stopped programmatically
`ProcessCrashed`	Child process exited with non-zero code unexpectedly
`BridgeUnavailable`	Enforcement was active but became unreachable — Nanny fails closed rather than continue ungoverned

Concepts

SDKs

Guides

CLI

Reference

Limits & Enforcement

The three limit types

Timeout

Steps

Tokens

Named limit sets

What happens when a limit is hit

​The three limit types

​Timeout

​Steps

​Tokens

​Named limit sets

​Named sets share one counter — they are not separate budgets

​What happens when a limit is hit

The three limit types

Timeout

Steps

Tokens

Named limit sets

Named sets share one counter — they are not separate budgets

What happens when a limit is hit