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.