Federate Ruflo Agents Across Machines, Nodes, and Orgs

Ruflo federation turns geographically distributed agent installations into a single cooperative swarm. Agents on your laptop, a remote server, a teammate’s machine, or a cloud node can discover each other, prove their identities, and exchange tasks — all with PII stripped before any data leaves a node and a full audit trail on both sides. You get the coordination of a unified swarm without giving up the isolation of separate machines. Key properties:

Ed25519 identity — each node generates a private key at init; peers exchange signed manifests with no central directory
Encrypted channels — WSS transport with permessage-deflate compression, optional cert pinning
No data leakage — a 14-type PII detection pipeline scans every outbound message before it leaves your node
Five-level trust ladder — UNTRUSTED → VERIFIED → ATTESTED → TRUSTED → PRIVILEGED; each level unlocks a wider set of operations
Behavioral trust scoring — formula (0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity) continuously evaluates peers; downgrades are instant
Budget circuit breaker — per-peer maxHops, maxTokens, and maxUsd caps prevent runaway delegation chains (ADR-097)

Install the Federation Plugin

# Via npm CLI
npx ruflo@latest plugins install -n ruflo-federation

# Via Claude Code plugin marketplace
/plugin install ruflo-federation@ruflo

Setup

Install the plugin on each node

Run the install command on every machine that will participate in the federation. Each node needs its own Ruflo installation and a copy of the federation plugin.

npx ruflo@latest plugins install -n ruflo-federation

Initialize a federation node

Initialize the node to generate an Ed25519 keypair and start the discovery service. This creates a signed manifest that peers will use to verify your identity.

{
  "tool": "federation_init",
  "params": {
    "nodeId": "my-mac",
    "endpoint": "ws://my-mac.tailnet:9100",
    "agentTypes": ["coder", "tester"]
  }
}

The keypair is persisted to .claude-flow/federation/keys-<nodeId>.json (mode 0600) and never transmitted in plaintext.Or via the CLI:

npx claude-flow@latest federation init

Join a peer node

Connect to another federation node by its endpoint. The handshake exchanges signed manifests, verifies Ed25519 signatures, and establishes an initial trust level of UNTRUSTED.

{
  "tool": "federation_join",
  "params": {
    "endpoint": "ws://other-host.tailnet:9100"
  }
}

Or via the CLI:

npx claude-flow@latest federation join wss://team-b.example.com:8443

Trust upgrades automatically as the peer accumulates successful interactions. Downgrades are instant if behavior degrades.

Verify peer discovery and connectivity

Check that your node sees its peers and that the trust ladder is progressing:

npx claude-flow@latest federation status

The MCP tool equivalent:

{
  "tool": "federation_status"
}

You should see each peer’s node ID, current trust level, and circuit-breaker state.

Sending Tasks Across Nodes

Once peers are connected, send tasks with optional spend caps:

# Send a task to a specific peer node
npx claude-flow@latest federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# With budget limits to prevent runaway fan-out
/federation send <node-id> task-assignment '{"task":"…"}' \
  --max-hops 4 \
  --max-tokens 50000 \
  --max-usd 0.25

Budget Field	Default	Notes
`maxHops`	`8`	`0` disallows remote delegation entirely. Hard ceiling 64.
`maxTokens`	unbounded	Σ tokens across the whole hop chain. Hard ceiling 1B.
`maxUsd`	unbounded	Σ USD across hops. Hard ceiling $1M.

Trust Levels and What Each Unlocks

Level	Capabilities	WG Mesh Reachability
`UNTRUSTED`	`discovery`	Excluded from mesh
`VERIFIED`	`+ status, ping`	Discovery port (9100) only
`ATTESTED`	`+ send, receive, query-redacted`	+ Federation messaging (9101–9199)
`TRUSTED`	`+ share-context, collaborative-task`	+ SSH (22), services (80/443)
`PRIVILEGED`	`+ full-memory, remote-spawn`	Full mesh

MCP Tools Reference

The ruflo-federation plugin ships MCP tools for the full federation lifecycle. The README confirms at minimum federation_init, federation_send, federation_trust, and federation_audit; the complete set exposed by the plugin is listed below:

Tool	Purpose
`federation_init`	Initialize this node, generate keypair
`federation_join`	Join a peer by endpoint
`federation_peers`	List discovered peers
`federation_send`	Send a typed message to a peer
`federation_query`	Synchronous query → response (`ATTESTED+` only)
`federation_status`	Current node + peer trust summary
`federation_trust`	View or adjust trust levels
`federation_audit`	Read the compliance audit log
`federation_breaker_status`	Per-peer circuit-breaker state
`federation_evict`	Operator manual evict of a peer
`federation_consensus`	Federated proposal across all peers

Use Cases

Distributed GPU Swarms

Distribute a large swarm across multiple GPU nodes. Each node runs specialized agents (model inference, embedding, etc.) and Ruflo coordinates task routing across the federation.

Security-Isolated Agents

Run security-sensitive agents on air-gapped or isolated machines. Federation sends only the task envelope — raw data never leaves the trusted node.

Team Memory Sharing

Share memory namespaces across team members’ installations. Patterns learned on one developer’s machine are immediately available to the whole team.

Compliance Workflows

HIPAA, SOC2, and GDPR audit trails are first-class primitives. Every federation event produces a structured audit record searchable via HNSW.

Optional WireGuard Mesh Layer (ADR-111)

For environments where packet-layer isolation matters, federation supports an opt-in WireGuard mesh that follows trust changes automatically. When a peer’s circuit breaker fires, the compromised peer is automatically isolated at Layer 3 — no manual firewall rule required. Enable in your federation plugin config:

{
  "federation": {
    "wgMesh": true
  }
}

Then run the staging helper to generate the WireGuard interface config and firewall projection:

node v3/@claude-flow/plugin-agent-federation/scripts/phase7-stage.mjs \
  <localNodeId> <peerNodeId> <peerPubkey> <peerMeshIP> <peerEndpoint>

Federation uses end-to-end Ed25519 signatures and encrypted WSS channels. Keys are generated locally during federation_init and stored at mode 0600 — they never leave the node in plaintext. The PII pipeline runs on every outbound message, scanning for 14 PII types (emails, SSNs, keys, and more) with per-trust-level policies: BLOCK, REDACT, HASH, or PASS.

For plugin details, see ruflo-federation and the full federation user guide at docs/federation/.

Get Started

Core Concepts

Guides

Configuration

Federate Ruflo Agents Across Machines, Nodes, and Orgs

Install the Federation Plugin

Setup

Sending Tasks Across Nodes

Trust Levels and What Each Unlocks

MCP Tools Reference

Use Cases

Distributed GPU Swarms

Security-Isolated Agents

Team Memory Sharing

Compliance Workflows

Optional WireGuard Mesh Layer (ADR-111)

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

Documentation Index

​Install the Federation Plugin

​Setup

​Sending Tasks Across Nodes

​Trust Levels and What Each Unlocks

​MCP Tools Reference

​Use Cases

Distributed GPU Swarms

Security-Isolated Agents

Team Memory Sharing

Compliance Workflows

​Optional WireGuard Mesh Layer (ADR-111)

Build docs developers (and LLMs) love

Install the Federation Plugin

Setup

Sending Tasks Across Nodes

Trust Levels and What Each Unlocks

MCP Tools Reference

Use Cases

Optional WireGuard Mesh Layer (ADR-111)