nanny run

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

# Starts a governor and runs [start].cmd from nanny.toml underneath it
nanny run --serve

# Append arguments to that command
nanny run --serve -- --verbose

Options

Flag	Type	Default	Description
`--join=<appId>`	string	—	Join an existing governance server by app id (from that server’s `.nanny/app.json`), instead of enforcing locally. Explicit and app-id-only: never a name, never auto-detected. Not compatible with `--serve`.
`--serve`	flag	—	Start the governance server, and launch `[start].cmd` underneath it when `nanny.toml` declares one. Omit `[start]` for a headless governor. See Governance server below.
`--no-sync`	flag	—	Do not forward events to Nanny Cloud for this run, even if `NANNY_API_KEY` is set. Enforcement is unaffected. See Connect to Nanny Cloud.
`--config=<path>`	path	`./nanny.toml`	Path to config file.

Exit codes

Code	Meaning
`0`	Process exited cleanly (`AgentCompleted`)
`1`	Nanny 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, 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,"run_id":"a1b2c3d4","seq":0,"command":"python agent.py","allowed_tools":["web_search","send_outreach"],"tool_labels":{"web_search":["reads_untrusted"],"send_outreach":["external_effect"]},"config_hash":"9f2a41c8"}
{"event":"RulesDeclared","ts":1711234567100,"run_id":"a1b2c3d4","seq":1,"rules":[{"name":"no_send_after_read","version":"1.0.0","pack":"nanny:recommended"}]}
{"event":"ToolAllowed","ts":1711234567120,"run_id":"a1b2c3d4","seq":2,"tool":"web_search","cleared_by":["no_send_after_read"]}
{"event":"RuleDenied","ts":1711234572000,"run_id":"a1b2c3d4","seq":3,"tool":"send_outreach","rule_name":"no_send_after_read","cleared_by":[]}
{"event":"ExecutionStopped","ts":1711234572000,"run_id":"a1b2c3d4","seq":4,"reason":"RuleDenied","tokens_spent":380,"elapsed_ms":5000}

Pipe to a file to keep your agent’s own output separate:

nanny run --serve > nanny.log

Governance server

nanny run --serve starts a long-lived governance server. Other processes and machines connect to it with nanny run --join=<appId>, and every tool call from every connected agent is evaluated against one shared set of rules. Whether it also runs an app of its own is decided by nanny.toml:

[start] present. The governor launches that command underneath itself, in one process. One container, one command, no launcher script. Trailing arguments after -- append to it.
[start] absent. A headless governor, for the case where the apps live elsewhere and arrive via --join.

Launching an app does not make the governor exclusive: it is still a server, and other processes can still join it, each with its own run id. Every run writes to the same log, and each event carries the run_id that tells them apart. Use it for everything. A single process gets a governor on loopback with no certificates and no setup, and several processes or machines get the same governor with an address and a bundle. One shape means the thing you run in development is the thing you run in production. Starting a server requires nanny init to have already run in that directory: the server’s state is keyed by the app’s permanent app_id, not a global path, so two unrelated apps’ servers on one machine never collide.

nanny run --serve [--addr <addr>] [--cert <path>] [--key <path>] [--ca <path>] [-- <args>]

It reads nanny.toml from the current directory and blocks until stopped (nanny stop or CTRL-C).

Serve flags

Flag	Type	Default	Description
`--addr`	socket address	`127.0.0.1:62669`	Listen address. Loopback is plain HTTP; non-loopback requires mTLS.
`--cert`	path	`~/.nanny/certs/server.crt`	Server TLS certificate PEM. Required only for non-loopback addresses.
`--key`	path	`~/.nanny/certs/server.key`	Server TLS private key PEM. Required only for non-loopback addresses.
`--ca`	path	`~/.nanny/certs/ca.crt`	CA certificate PEM used to validate agent client certs. Required only for non-loopback addresses.

The bind address sets the security posture: loopback (127.0.0.1) is plain HTTP for same-machine agents; a non-loopback address (0.0.0.0) makes mTLS mandatory, and the server refuses to start without certs. For cross-machine setup, certificates, and connecting agents, see the Governance server guide.

Manage a running server

nanny status                  # current directory's own app, by .nanny/app.json
nanny status --app=<appId>    # or target a specific app explicitly

nanny stop                    # SIGTERM, then a 10-second graceful drain
nanny stop --app=<appId>

Both commands default to the current directory’s own app_id when --app is omitted. nanny status reads ~/.nanny/servers/<appId>/server.addr and probes the server (exit 0 if reachable, 1 otherwise). nanny stop reads the PID from ~/.nanny/servers/<appId>/server.pid and sends SIGTERM (on Windows, taskkill /F).

Relocating the state directory

Set NANNY_HOME to put .nanny/servers/ (and everything else normally under ~/.nanny/) somewhere other than the home directory:

NANNY_HOME=/opt/nanny nanny run --serve
NANNY_HOME=/opt/nanny nanny run --join=<appId>

Both sides of a --serve/--join pair need the same NANNY_HOME to find each other’s state. Falls back to the OS home directory when unset.

For per-function governance (marking individual tools and rules in code), see the Rust SDK guide or Python SDK guide.

Concepts

SDKs

Guides

CLI

Reference

Examples

Options

Exit codes

Stderr

Event log

Governance server

Serve flags

Manage a running server

Relocating the state directory

​Examples

​Options

​Exit codes

​Stderr

​Event log

​Governance server

​Serve flags

​Manage a running server

​Relocating the state directory

Examples

Options

Exit codes

Stderr

Event log

Governance server

Serve flags

Manage a running server

Relocating the state directory