Governance server

When to use the governance server

For most projects, nanny run is all you need. It starts a local enforcement bridge inside the same process group as your agent, governs it, and exits when the agent exits. No server. No cert setup. No network. Use the governance server when agents run in separate processes or on separate machines and you need a shared enforcement boundary across all of them. Common scenarios:

Microservices: three containers, each running an agent, all sharing a single token budget
CI workers: a coordinator spins up worker processes on different machines; you want each worker’s tool calls counted against the same budget
Development clusters: a Kubernetes pod runs the server; a local dev agent connects to it while you iterate

If your agents all run inside a single nanny run — even a complex CrewAI or LangGraph pipeline with many agents — you do not need the governance server.

The three deployment modes

Mode	Command	Transport	When to use
Local inline	`nanny run`	Unix socket / TCP loopback (OS-enforced)	Single process, single machine — the default
Local governance server	`nanny server start`	Plain HTTP on loopback — no certs needed	Multiple processes on one machine
Cross-machine governance server	`nanny server start --addr 0.0.0.0:62669`	mTLS — mandatory, certs required	Docker, Kubernetes, remote agents

The bind address determines the security posture. The default (127.0.0.1:62669) is loopback — plain HTTP, no cert setup required. Binding to a non-loopback address enables network access and makes mTLS mandatory; the server refuses to start without cert files.

Setup: local (same machine, no certs required)

This covers the common case where all your agents run on the same machine but in separate processes. 1. Start the server:

nanny server start

The server starts on 127.0.0.1:62669 (loopback) by default, generates a session token, and writes both the address and token to ~/.nanny/ so nanny run can detect them. The token is printed at startup for reference. No certs needed. 2. Run your agents — no configuration needed:

nanny run

When a governance server is running on the same machine, nanny run detects it automatically from ~/.nanny/server.addr and ~/.nanny/server.token, then injects NANNY_BRIDGE_ADDR and NANNY_SESSION_TOKEN into the agent process. You set nothing manually. A confirmation message appears before your agent starts:

nanny: network server detected at 127.0.0.1:62669
nanny: governance enforced remotely — limits and rules apply

Setup: cross-machine (mTLS required)

When your agents run on different machines, the server must verify that only your agents can connect — not anyone else on the network.

Step 1: Generate certificates

nanny certs generate

This creates five files in ~/.nanny/certs/:

ca.crt      — CA certificate (the trust anchor — share with all agents)
ca.key      — CA private key (keep this on the server machine only)
server.crt  — server certificate (used by nanny server start)
server.key  — server private key (keep this on the server machine only)
client.crt  — client certificate (copy to each agent machine)
client.key  — client private key (copy to each agent machine)

Default validity: 365 days. To see expiry dates at any time:

nanny certs show

Step 2: Start the server

nanny server start --addr 0.0.0.0:62669

The server automatically reads server.crt, server.key, and ca.crt from ~/.nanny/certs/. Pass explicit paths if your certs are elsewhere:

nanny server start --addr 0.0.0.0:62669 \
  --cert /path/to/server.crt \
  --key  /path/to/server.key \
  --ca   /path/to/ca.crt

Important: The server will refuse to start if any cert file is missing. Run nanny certs generate first or provide paths to existing cert files.

Step 3: Distribute client certificates

Copy client.crt, client.key, and ca.crt to each agent machine. These are the only files agents need. The ca.key and server.key never leave the server machine.

Step 4: Configure your agents

The session token is generated by the server at startup and saved to ~/.nanny/server.token on the server machine. Copy it:

cat ~/.nanny/server.token

On each agent machine, create a .env file with the token value you just copied and the cert paths from Step 3:

# .env (never commit this file — add it to .gitignore)
NANNY_BRIDGE_ADDR=server.example.com:62669
NANNY_SESSION_TOKEN=<paste value from ~/.nanny/server.token>
NANNY_BRIDGE_CERT=/path/to/client.crt
NANNY_BRIDGE_KEY=/path/to/client.key
NANNY_BRIDGE_CA=/path/to/ca.crt

For Docker or Kubernetes, pass these as deployment secrets (environment: in Docker Compose, a k8s Secret, or CI/CD secret injection) rather than a file. When an agent is launched with nanny run and these variables are set, it connects to the governance server with mTLS. The server verifies the client certificate and refuses connections from anything without a valid cert signed by the same CA.

Shared budget

All agents connected to the same governance server share one enforcement state. Token budget, steps, and timeout are tracked across all of them simultaneously. This means:

If Agent A spends 400 tokens and Agent B spends 600, and the budget is 1000, the next call from either agent stops the execution — regardless of which agent makes it.
A loop in Agent B counts toward the global step limit alongside Agent A’s steps.

The governance server is a shared enforcement layer for a team of agents working on one task. Each agent is subject to the same limits as every other agent. Named limits still work the same way. When an agent activates @agent("researcher"), it enters the [limits.researcher] scope from nanny.toml. That scope’s ceiling applies for the duration of that function. The shared token budget still tracks totals across all agents — a named scope does not isolate budget from other agents, it only sets the ceiling for that scope.

Server management

# Show address, PID, and reachability
nanny server status

# Stop the server (sends SIGTERM, 10-second graceful drain)
nanny server stop

# Check all active Nanny components at once
nanny health

nanny server stop sends SIGTERM to the server process. In-flight requests complete within a 10-second grace window before the server exits. This means a running agent can finish its current tool call before the server shuts down.

Certificate operations

# Regenerate server + client certs (preserves the CA)
nanny certs rotate

# Show expiry dates and SAN list
nanny certs show

# Import externally-issued certs (BYOC — HashiCorp Vault, AWS ACM, etc.)
nanny certs import ca=@/path/to/ca.crt cert=@/path/to/server.crt key=@/path/to/server.key

# Remove all certs from ~/.nanny/certs/ (asks for confirmation)
nanny certs remove

Certificate hot-reload

The server watches ~/.nanny/certs/ for file changes. When any cert file is replaced — by nanny certs rotate, nanny certs import, or a PKI automation system writing to the directory — the server reloads the cert into memory without restarting. New connections use the new cert immediately; existing connections finish on the old cert. This matters for short-lived PKI certs (for example, 8-hour Vault-issued certs renewed by Vault Agent) — you do not need to restart the governance server when certs are rotated.

Externally-issued certificates (BYOC)

If your organization uses HashiCorp Vault, AWS ACM, cert-manager, or any other PKI system, you can import those certs directly:

# From files
nanny certs import \
  ca=@/vault/secrets/ca.pem \
  cert=@/vault/secrets/tls.crt \
  key=@/vault/secrets/tls.key

# From environment variables (Vault Agent injection, CI/CD secrets)
nanny certs import \
  ca="$VAULT_CA" \
  cert="$VAULT_CERT" \
  key="$VAULT_KEY"

# Partial import — update only the cert and key, keep the existing CA
nanny certs import cert=@new-server.crt key=@new-server.key

Partial imports are supported: omit any key to leave the existing file unchanged. After any import, Nanny validates that the imported cert is signed by the imported (or existing) CA and fails loudly on a mismatch. nanny certs rotate works only when nanny certs generate created the CA — because it needs the CA private key (ca.key) on disk to sign new certs. For externally-issued certs, the CA private key never leaves your PKI system. Use nanny certs import instead for rotation.

HTTP proxy mode

The governance server can also act as an HTTP CONNECT proxy on the same port. Any outbound HTTP or HTTPS request your agent makes through the proxy is subject to Nanny’s allowlist — even calls from code that has no @nanny_tool decorator. See HTTP proxy mode for setup and configuration.

Port 62669

The governance server listens on port 62669 by default. Both the governance API and the HTTP CONNECT proxy share this port. 62669 spells NANNY on a phone keypad (N=6, A=2, N=6, N=6, Y=9). Genuinely memorable for ops and firewall rules.

Concepts

SDKs

Guides

CLI

Reference

When to use the governance server

The three deployment modes

Setup: local (same machine, no certs required)

Setup: cross-machine (mTLS required)

Step 1: Generate certificates

Step 2: Start the server

Step 3: Distribute client certificates

Step 4: Configure your agents

Shared budget

Server management

Certificate operations

Certificate hot-reload

Externally-issued certificates (BYOC)

HTTP proxy mode

Port 62669

​When to use the governance server

​The three deployment modes

​Setup: local (same machine, no certs required)

​Setup: cross-machine (mTLS required)

​Step 1: Generate certificates

​Step 2: Start the server

​Step 3: Distribute client certificates

​Step 4: Configure your agents

​Shared budget

​Server management

​Certificate operations

​Certificate hot-reload

​Externally-issued certificates (BYOC)

​HTTP proxy mode

​Port 62669

When to use the governance server

The three deployment modes

Setup: local (same machine, no certs required)

Setup: cross-machine (mTLS required)

Step 1: Generate certificates

Step 2: Start the server

Step 3: Distribute client certificates

Step 4: Configure your agents

Shared budget

Server management

Certificate operations

Certificate hot-reload

Externally-issued certificates (BYOC)

HTTP proxy mode

Port 62669