Skip to main content
Spawns a child process under full Nanny enforcement. Reads nanny.toml from the current directory and kills the process the moment any limit is crossed. 
nanny run [OPTIONS] [-- ARGS...]

​
Examples

# Run with base [limits] (reads [start].cmd from nanny.toml)
nanny run

# Run with a named limit set
nanny run --limits=researcher

​
Options

FlagTypeDefaultDescription
--limits=<name>string—Activate a named limit set from nanny.toml. Inherits from [limits].
--config=<path>path./nanny.tomlPath to config file.

​
Exit codes

CodeMeaning
0Process exited cleanly (AgentCompleted)
1Nanny stopped the process, a spawn failure occurred, or an internal error occurred

​
Stderr

When Nanny stops a process it prints the reason to stderr: 
nanny: stopped — TimeoutExpired
nanny: stopped — BudgetExhausted
nanny: stopped — MaxStepsReached
nanny: stopped — ToolDenied
nanny: stopped — RuleDenied
This message is separate from the structured event log, which goes to stdout (or a configured file).

​
Event log

Every run emits NDJSON events to stdout. ExecutionStarted is always first; ExecutionStopped is always last: 
{"event":"ExecutionStarted","ts":1711234567000,"limits":{"steps":100,"cost":1000,"timeout":30000},"limits_set":"[limits]","command":"python agent.py"}
{"event":"ToolAllowed","ts":1711234567120,"tool":"http_get"}
{"event":"StepCompleted","ts":1711234567800,"step":1}
{"event":"ExecutionStopped","ts":1711234572000,"reason":"BudgetExhausted","steps":12,"cost_spent":1000,"elapsed_ms":5000}
Pipe to a file to keep your agent’s own output separate: 
nanny run > nanny.log

​
What nanny run does not do

  • It does not retry. A stop is final.
  • It does not interpret what your agent is doing. It only counts and times.
  • Timeout enforcement works with any binary in any language. Per-function cost metering and custom rules require SDK annotations.
For per-function governance (marking individual tools and rules in code), see the Rust SDK guide.