nanny.toml reference

Full schema

# ── Runtime ─────────────────────────────────────────────────────────────────────────────

[runtime]
mode = "local"   # "local" | "managed"

# ── Start ─────────────────────────────────────────────────────────────────────

[start]
cmd = "python agent.py"   # required, the command nanny run executes

# ── Limits ────────────────────────────────────────────────────────────────────

[limits]
steps   = 100
tokens  = 1000
timeout = 30000

# Named limit sets — inherit from [limits], override only declared fields.
[limits.researcher]
steps   = 200
tokens  = 5000
timeout = 120000

# ── Tools ─────────────────────────────────────────────────────────────────────

[tools]
allowed = ["http_get", "read_file"]   # empty list denies every tool call

# Per-tool configuration — tool name must match the function name in code.
[tools.http_get]
max_calls       = 10    # max number of calls in one execution
tokens_per_call = 20    # overrides the decorator/macro default if set

# ── Observability ─────────────────────────────────────────────────────────────

[observability]
log      = "stdout"          # "stdout" | "file"
log_file = "nanny.log"       # Required when log = "file"

# ── Proxy ─────────────────────────────────────────────────────────────────────

[proxy]
allowed_hosts = ["api.openai.com", "*.anthropic.com"]   # required when proxy mode is used

# ── Managed (Cloud) ───────────────────────────────────────────────────────────

[managed]
endpoint = "https://api.nanny.run/v1"
# The key comes from the NANNY_API_KEY environment variable:
#   export NANNY_API_KEY="nny_..."

[runtime]

Field	Type	Default	Description
`mode`	`"local"` \| `"managed"`	`"local"`	`"local"` uses the local enforcement bridge. `"managed"` connects to a Nanny Cloud endpoint (requires `[managed]`).

[start]

Field	Type	Default	Description
`cmd`	string	—	Required. The shell command `nanny run` executes. Examples: `"python agent.py"`, `"cargo run --release"`, `"node agent.js"`.

[limits]

The global execution ceiling. Any one limit stopping the agent stops the entire run.

Field	Type	Default	Description
`steps`	integer	—	Maximum tool calls allowed. Requires SDK instrumentation.
`tokens`	integer	—	Maximum tokens allowed. Requires SDK instrumentation.
`timeout`	integer (ms)	—	Maximum wall-clock time in milliseconds. Enforced for any process, no SDK required.

Named limit sets — [limits.<name>] inherits all fields from [limits] and overrides only the fields it declares:

[limits]
steps   = 50
tokens  = 500
timeout = 15000

[limits.researcher]
steps   = 200       # overrides 50
tokens  = 5000      # overrides 500
# timeout inherits 15000

[limits.reporter]
tokens  = 100       # overrides 500 only; steps and timeout inherit

Activate a named set from the CLI:

nanny run --limits=researcher

Or from inside agent code using @agent("researcher") (Python) or #[nanny::agent("researcher")] (Rust).

[tools]

Field	Type	Default	Description
`allowed`	string array	—	Explicit allowlist of tool names. An empty array denies every tool call. If `[tools]` is not present, all tools are allowed.

Per-tool configuration — `[tools.<name>]`

[tools.http_get]
max_calls       = 10
tokens_per_call = 20

Field	Type	Default	Description
`max_calls`	integer	unlimited	Maximum number of calls to this tool in one execution. Exceeding this limit fires `RuleDenied` with `rule_name = "<tool>.max_calls"`.
`tokens_per_call`	integer	decorator/macro value	Tokens charged per call. Overrides the value declared in `@tool(tokens=N)` or `#[tool(tokens = N)]`.

The tool name in [tools.<name>] must exactly match the function name used in the @tool decorator or #[nanny::tool] macro.

[observability]

Field	Type	Default	Description
`log`	`"stdout"` \| `"file"`	`"stdout"`	Destination for the NDJSON event stream.
`log_file`	string	—	Required when `log = "file"`. Path to the output file.

[proxy]

Optional. Enables HTTP CONNECT proxy mode on the governance server. Proxy mode is active only when allowed_hosts is present and non-empty. An empty list — or omitting [proxy] entirely — disables proxy mode.

Field	Type	Default	Description
`allowed_hosts`	string array	`[]`	Hostnames the proxy may forward to. Supports exact names (`api.openai.com`) and `*.suffix` wildcard patterns. Loopback, link-local, and RFC-1918 ranges are always blocked regardless of this list.

See HTTP proxy mode for full details.

[managed]

Only read when [runtime] mode = "managed". Cloud connection config.

Field	Type	Default	Description
`endpoint`	string	—	Nanny Cloud API endpoint.
`api_key`	string	—	Optional, and not recommended. A local-experimentation escape hatch. Prefer `NANNY_API_KEY` (below), which overrides this field.

Supplying the API key

The key is read from the NANNY_API_KEY environment variable, so nanny.toml stays safe to commit:

export NANNY_API_KEY="nny_..."
nanny run

Resolution order:

NANNY_API_KEY — wins whenever it is set to a non-empty value.
[managed] api_key in nanny.toml — fallback.

A blank or whitespace-only NANNY_API_KEY counts as unset (an unset CI secret usually surfaces as ""), so it falls through to the config file rather than authenticating with an empty string. If no key is found, Nanny prints a warning and keeps enforcing locally — it simply does not forward events to the cloud. Enforcement never depends on the network.

Your organization is derived from the API key on the cloud side, so there is no org_id field to configure.

Concepts

SDKs

Guides

CLI

Reference

nanny.toml reference

Full schema

[runtime]

[start]

[limits]

[tools]

Per-tool configuration — `[tools.<name>]`

[observability]

[proxy]

[managed]

Supplying the API key

​Full schema

​[runtime]

​[start]

​[limits]

​[tools]

​Per-tool configuration — [tools.<name>]

​[observability]

​[proxy]

​[managed]

​Supplying the API key

Full schema

[runtime]

[start]

[limits]

[tools]

Per-tool configuration — `[tools.<name>]`

[observability]

[proxy]

[managed]

Supplying the API key