Skip to main content
The governance server is a long-lived daemon that enforces Nanny’s limits across multiple processes and machines. Agents connect to it over TCP. All tool calls from all connected agents are counted against the same shared budget and step limit. For single-process agents, use nanny run instead — no server needed.

​
Commands

​
start

Start the governance server.
Reads nanny.toml from the current directory. Blocks until the server is stopped with nanny server stop or CTRL-C.

​
Flags

​
Security posture by bind address

The bind address determines whether TLS is required:

​
Examples

Local dev — multiple processes on one machine:
Cross-machine — Docker or Kubernetes:
Custom cert paths:

​
What gets written

When the server starts, it writes two files:
  • ~/.nanny/server.addr — the bound listen address (used by nanny server status and nanny health)
  • ~/.nanny/server.pid — the server process ID (used by nanny server stop)

​
HTTP proxy mode

If nanny.toml includes a [proxy] section with a non-empty allowed_hosts list, the server also acts as an HTTP CONNECT proxy on the same port. See HTTP proxy mode.

​
status

Show the live status of the running server.
Reads ~/.nanny/server.addr, attempts a TCP connection, and reports whether the server is reachable. Example output (server running):
Example output (server not reachable):
Exits 0 if the server is running and reachable, 1 otherwise.

​
stop

Stop the running server.
Reads the PID from ~/.nanny/server.pid and sends SIGTERM. The server begins a graceful shutdown:
  1. Stops accepting new connections.
  2. Allows in-flight requests to complete (up to 10 seconds).
  3. Exits cleanly.
On Windows, uses taskkill /F instead of SIGTERM. If the server is not running:

​
Connecting agents

Same-machine agents: nanny run detects the server automatically via ~/.nanny/server.addr and ~/.nanny/server.token and injects all required variables into the agent process. Nothing to set manually. Cross-machine agents: Set these in your deployment config (Docker Compose environment:, k8s Secret, CI/CD secrets): These variables are internal — set by nanny run or your deployment config. Do not set them for same-machine agents; nanny run handles them automatically.

​
Port 62669

The governance server default port is 62669. This port serves both the governance JSON API and the HTTP CONNECT proxy. There is no separate proxy port. 62669 spells NANNY on a phone keypad.