> ## Documentation Index > Fetch the complete documentation index at: https://docs.nanny.run/llms.txt > Use this file to discover all available pages before exploring further. # Governance server > Run Nanny enforcement across multiple processes and machines using the standalone 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:** ```bash theme={null} 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:** ```bash theme={null} 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 ```bash theme={null} 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: ```bash theme={null} nanny certs show ``` ### Step 2: Start the server ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```ini theme={null} # .env (never commit this file — add it to .gitignore) NANNY_BRIDGE_ADDR=server.example.com:62669 NANNY_SESSION_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 ```bash theme={null} # 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 ```bash theme={null} # 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: ```bash theme={null} # 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](/v0.4/guides/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.