Federation & cloud nodes

Most teams run a single instance. Federation is for when you want several instances to act as one connected fleet — for isolation, scale, or reach. Each function (marketing, support, ops) can be its own isolated runtime, while you still see and govern them from one place.

The model#

Federation is hub-and-spoke. A hub instance coordinates one or more node instances. Cross-instance requests are cryptographically signed, so a node can trust that a request really came from its hub.

The load-bearing property: a node is a separate, isolated runtime — its own database, its own secrets, its own COO, usually its own host. Nodes cannot talk to each other; the only path is hub→node, and it's policy-gated. Agents on different nodes are islands.

Note — Isolation is by construction, not by rule. Marketing's agent can't reach Ops' secrets because they're on different machines with no path between them — not because a policy says no.

Isolated by function, seen in one place#

Federated agents aren't hidden away — they appear alongside your local agents, marked with a 🌐 node chip:

• in the sidebar and on the Agents page,
• as bounded "rooms" per node on the Team canvas,
• and in the Oversight → Registry inventory.

So you get the isolation your security team wants without losing the single pane of glass.

Provider credentials, per node#

When you spawn a node you choose how it gets its model keys:

• Inherit hub keys (default) — shares the hub's providers; works out of the box.
• Isolated — no keys are injected; the node brings its own (set them on the node's own Settings → Model Providers). Full credential isolation — the hub's keys never touch it.
• Give it its own keys — you enter per-node keys right in the Spawn dialog.

The node row badges the posture (shared / isolated / custom keys).

The seam — and the human bridge#

Every node has a dispatch policy (the "seam") that controls who on the hub may dispatch into it: closed, coo-only (the safe default), approval-required, or open. It's set per node, with a workspace-wide default.

Because agents don't cross the seam, a human does — you can query a remote agent from its channel, and every crossing is recorded on the tamper-evident audit chain with full provenance.

You can also make any agent an island with one click ("Silo") — it can neither delegate to, nor receive delegations from, any other agent, while humans can still query it.

Governing the fleet (Enterprise)#

On the Enterprise tier, federation becomes a governed fleet from one console:

• Isolated runtimes, one workspace. Each function runs as its own isolated instance — own runtime, own secrets, own COO — presented as one workspace, with per-function admins.
• Baseline + per-node rules. Set a security baseline once and it holds across every node; tighten it per node where you need to. Because you provision the nodes, the guardrails are set at creation.
• Three-tier roles. Govern (operators set the baseline and security rules), manage (a scoped admin runs a node's agents within the guardrails), query (members talk to agents where policy allows).
• Fleet posture & drift. The console shows the whole fleet's posture at a glance and flags any node that drifts from the baseline — on the tamper-evident chain.

Ceiling — These controls govern the seam and the baseline you provision, recorded tamper-evidently. Each node still enforces its own policy locally and keeps its own audit chain: central governance is real because you provision the nodes, but a node you don't control is trusted-and-verified, not remotely forced. Sovereignty runs both ways.

Cloud nodes#

Beyond standing nodes, the hub can spawn ephemeral cloud nodes for burst work — provisioned to run a task, then torn down.

Requirements & ceilings#

Ceiling — damn.dev governs the seam (who may dispatch into a node) and records the human bridge (every cross-instance query, on the audit chain). It does not observe a remote agent's internal actions — those run on that node and land on that node's own audit chain. Federation gives you inventory + seam control across the fleet, not observation inside each box.

Ceiling — Cloud nodes need the hub reachable at a public URL (FEDERATION_PUBLIC_URL) — cloud-node provisioning refuses a localhost hub. This is a networked, operationally-involved feature; plan for a real hostname and the egress between hub and nodes.

Note — A node is a separate host with its own data and secrets. Federation connects instances; it does not merge their data directories.

Setting it up#

Federation is configured from Settings → Federation on the hub. Because it's deployment-specific (your hostnames, your network), this page is a conceptual overview — the in-product Federation settings walk you through wiring a node, and cloud-node provisioning needs the public-hub-URL prerequisite above.

Next#

• Data, backups, networking & updates — the networking prerequisites.
• Architecture, gateways & runtime — what a single instance is, before you connect several.