Federation

NANDA registries can federate — synchronizing agent listings across independent nodes so that agents registered on one node become discoverable on all connected peers.

Pull-based model Federation uses a gossip-based sync model. Each node periodically fetches GET /list from its configured peers and upserts agents with source = peerUrl to distinguish local vs federated entries.

How It Works

Step 1

Peer Discovery

A registry is configured with one or more peer URLs via the NANDA_FEDERATION_PEER_URL environment variable. Each peer must expose the standard NANDA API.

Step 2

Sync Trigger

Sync is triggered via POST /federation/sync (uses the configured peer) or POST /federation/sync-peer (specify a custom peer URL). Both require admin authentication.

Step 3

Agent Upsert

The sync process fetches GET /list from the peer, then for each agent: inserts new agents or updates existing federated entries. Local agents (source = 'local') are never overwritten.

API Endpoints

POST /federation/sync

Trigger sync from the configured peer (NANDA_FEDERATION_PEER_URL). Requires Authorization: Bearer $ADMIN_KEY.

POST /federation/sync-peer

Sync from a specific peer URL provided in the request body. Requires admin authentication. Prevents SSRF via auth gate.

GET /federation/agents

List all federated (non-local) agents, ordered by most recently updated.

GET /federation/status

Returns per-peer sync status: agent count and last sync timestamp for each federated source.

POST /federation/gossip

CRDT gossip inbound endpoint. Receives and merges agent state from peer registries using LWW-Element-Set CRDTs. Requires admin authentication.

GET /federation/peers

Returns all known federation peer registries with status and last sync time.

Sync Result

Each sync operation returns a result object:

{
  "peerUrl": "https://peer-node.example.com",
  "imported": 12,
  "updated": 3,
  "errors": 0,
  "durationMs": 847
}

Data Model

Federated agents are stored in the same agents table as local agents. The source column distinguishes origin:

  • source = 'local' — registered directly on this node
  • source = 'https://peer.example.com' — imported via federation sync from that peer URL

During sync, only agents where source matches the peer URL are updated — local agents are never overwritten by federation.

Configuration

NANDA_FEDERATION_PEER_URL

URL of the default peer registry for /federation/sync

NANDA_FEDERATION_ADMIN_KEY

Bearer token required for all sync endpoints — prevents unauthorized sync triggers

NANDA_NODE_ID

Unique identifier for this node in the gossip protocol — used in peer registration and vector clocks

See also API Reference for the full endpoint list · Trust & Security for credential verification across federated nodes
Related reading CRDTs & Gossip Protocols — how NANDA keeps federated registries in sync · The Quilt Architecture — federated overlays for agent discovery · Trust Without Borders — cross-registry identity in the Agentic Web series

Coming Soon

By Invitation Only