Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md
phase7-mesh-bringup.md	phase7-mesh-bringup.md

Ruflo Federation — User Guide

Cross-installation agent peering with built-in cost limits, circuit breaker, signed envelopes, and (as of alpha.14) opt-in WireGuard mesh layer governed by federation trust.

This guide walks through what federation is, when to use it, and how to set it up. For the architectural backstory and per-phase release notes see the companion gist.

What federation does

Federation lets two or more Ruflo installations — your mac, a server, a teammate's laptop — discover each other, exchange signed manifests, and send messages between them with bounded cost and per-peer trust gates. Key properties:

Ed25519 identity — each node holds a private key; peers exchange Ed25519-signed manifests. No central directory.
Five-level trust ladder — UNTRUSTED → VERIFIED → ATTESTED → TRUSTED → PRIVILEGED. Each level unlocks a wider set of operations (discovery, send, share-context, remote-spawn, …).
Per-peer budget + circuit breaker — bounded tokens/USD per peer. Sustained failures auto-SUSPEND; further failures EVICT. ADR-097.
PII pipeline + audit trail — every cross-peer envelope passes through PII detection. Every state transition is auditable.
Real wire transport — WSS with permessage-deflate compression, optional cert pinning, stream multiplexing. ADR-104.
Optional WG mesh layer — opt-in opaque packet-layer reachability that follows federation trust changes. Compromised peer auto-isolated at L3 when the breaker fires. ADR-111.

When to use federation

Use case	Fit
Two laptops collaborating on a project, want bounded cost sharing + audit	✅
Personal home server agent ↔ travel laptop	✅
Team of 5 engineers sharing memory/skills across machines	✅
Mobile / Windows / sub-50 peers with NAT issues	✅ over Tailscale + federation
Public-internet exposed agent endpoints	✅ with TLS cert pinning (ADR-107)
Internal HR/finance multi-agent workflow with strict access tiers	✅ with PRIVILEGED gating + audit
Replacing Slack/Discord — no	❌ federation is for agent-to-agent, not human chat
Untrusted-internet messaging without identity vetting	❌ — trust ladder must be bootstrapped out-of-band

Quick start

1. Install the plugin

npx ruflo@latest                                     # if you don't have it yet
npx ruflo plugins install @claude-flow/plugin-agent-federation

Or directly via npm:

npm i @claude-flow/plugin-agent-federation@latest    # currently 1.0.0-alpha.14

2. Initialize a node

npx claude-flow@v3alpha agent spawn -t federation --name fed-1

Or via the MCP tool federation_init:

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

This generates an Ed25519 keypair (persisted to .claude-flow/federation/keys-<nodeId>.json, mode 0600), publishes a signed manifest, and starts the discovery service.

3. Join a peer

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

The handshake exchanges manifests, verifies Ed25519 signatures, and establishes the initial trust level (UNTRUSTED until the trust-evaluator records enough successful interactions to promote).

4. Send a message

{
  "tool": "federation_send",
  "params": {
    "targetNodeId": "other-host",
    "messageType": "agent-handoff",
    "payload": { "task": "Investigate the failing integration test" }
  }
}

Budget and trust gates apply: if the peer is below ATTESTED, only discovery/status/ping go through. If the breaker has the peer SUSPENDED, the send short-circuits with PEER_SUSPENDED.

MCP tools at a glance

Tool	What it does	Trust gate
`federation_init`	Initialize this node	—
`federation_join`	Join a peer by endpoint	—
`federation_peers`	List discovered peers	—
`federation_send`	Send a typed message to a peer	per-peer (varies)
`federation_query`	Synchronous query → response	`ATTESTED+`
`federation_status`	Current node + peer trust summary	—
`federation_trust`	View / adjust trust levels	operator
`federation_audit`	Read audit log	operator
`federation_breaker_status`	Per-peer state, when changed, why	—
`federation_evict`	Operator manual evict	operator
`federation_reactivate`	Operator manual reactivate	operator
`federation_report_spend`	Report cost of a completed call	integrator
`federation_consensus`	Federated proposal across peers	varies
`federation_wg_status`	(ADR-111) Per-peer mesh state	—
`federation_wg_attest`	(ADR-111) Operator-signed witness entry	operator
`federation_wg_keyrotate`	(ADR-111) Rotate WG keypair	operator + `confirm:true`

Trust levels — what each unlocks

Level	Capabilities (federation)	WG reachability (if ADR-111 active)
`UNTRUSTED`	`discovery`	Excluded from mesh — drop all
`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

Trust is earned via repeated successful interactions (the TrustEvaluator tracks score + interaction count). Promotion thresholds are documented in domain/entities/trust-level.ts.

Circuit breaker

If a peer's failure ratio or cost spend exceeds the policy:

ACTIVE → SUSPENDED → EVICTED
   ↑          │
   └─────────operator-only─────────┘

SUSPEND: peer's outbound sends short-circuit (PEER_SUSPENDED). Existing sessions continue; new sends rejected. Auto-eviction on continued failures.
EVICT: peer's outbound sends short-circuit (PEER_EVICTED). Session terminated. Operator must explicitly reactivate.
The breaker does not auto-reactivate. The integrator's health probe is responsible for confirming the peer is healthy and calling federation_reactivate.

Policy is tunable; defaults are conservative (50+ samples needed before suspend, high failure ratio threshold).

ADR-111 — WireGuard mesh (opt-in, since alpha.14)

Federation today treats network connectivity as the integrator's problem (Tailscale, LAN, wss://+pinning). That works but trust changes don't propagate to the L3 layer — a peer EVICTED in federation stays in the tailnet until an admin manually removes it.

ADR-111 closes that gap with an optional in-tree WG mesh:

WG keypair generated alongside the federation key
Mesh IP derived deterministically from nodeId (sha256 → 10.50.0.0/16 host portion, with collision-handling probe loop)
WG identity published inside the same Ed25519-signed manifest
Federation breaker SUSPEND → wg set ... allowed-ips "" (soft-block at L3)
Federation breaker EVICT → wg set ... remove (terminal)
Operator reactivate → AllowedIPs restored
Each mutation entered into an append-only Ed25519-signed witness chain

Phases shipped in alpha.14:

Phase 1 — Manifest extension + key generation
Phase 2 — WgMeshService (no shell — emits configs + commands)
Phase 3 — Coordinator/breaker wiring
Phase 4 — Firewall projection (nftables / pf) — PR #1895
Phase 5 — Witness attestation chain — PR #1895
Phase 6 — Operator MCP tools — PR #1895

Phase 7 — operator-mediated: See docs/federation/phase7-mesh-bringup.md for the cross-OS bringup procedure (mac ↔ ruvultra over Tailscale).

Enabling ADR-111

Set config.wgMesh: true in your federation plugin config, then run the staging helper:

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

The script generates /tmp/adr-111-stage/:

wg-key-<nodeId>.json (mode 0600 — your private WG key)
ruflo-fed.conf (the wg-quick interface config)
ruflo-fed.nft or ruflo-fed.pf (firewall projection)

After review, the operator manually activates:

sudo install -m 0600 /tmp/adr-111-stage/ruflo-fed.conf /etc/wireguard/ruflo-fed.conf
# Linux:
sudo nft -f /tmp/adr-111-stage/ruflo-fed.nft
# macOS:
sudo pfctl -a ruflo-fed -f /tmp/adr-111-stage/ruflo-fed.pf
sudo wg-quick up ruflo-fed

Using `claude -p` headless mode

claude -p (print/pipe mode) can drive federation MCP tools non-interactively. Each invocation processes its prompt and exits — for a persistent federation listener, run a long-lived MCP server instead.

On the originating host (mac mini):

claude -p --model haiku --max-budget-usd 0.20 --output-format text \
  "Federation MCP tools to verify cross-machine peering health: name 3. One line."
# → Three Federation MCP tools for peering health verification:
#   federation-init (keypair generation), federation-status (peers/trust/metrics),
#   federation-audit (compliance filtering).

On the peer host (ruvultra) — requires interactive /login first since claude -p reads stored credentials:

# First time only — operator-mediated:
claude   # then /login

# After that:
claude -p --model haiku --max-budget-usd 0.20 \
  "Run federation_status MCP and report peer count."

Workflow for cross-machine task handoff:

# Host A — kick off a federated task:
claude -p --model sonnet --output-format json --resume <session> \
  "Use federation_send to dispatch this task to ruvultra: analyze the failing test"

# Host B (ruvultra) — receive + work:
claude -p --resume <session> "Continue handling the federated task"

The federation plugin handles signing, PII gating, breaker, and audit on every send. The two claude -p invocations don't share state directly — they communicate exclusively through the federation envelope channel.

Anti-goals — when NOT to use federation

Replacement for Slack/Discord. Federation moves agent envelopes, not human chat.
Public internet without identity vetting. Trust ladder bootstrapping is your responsibility.
NAT traversal magic. Use Tailscale (or Headscale) for that; federation rides on top.
A general-purpose RPC framework. It's specifically for AI agents with cost-aware budgeting.

Where things live

What	Path
Plugin source	`v3/@claude-flow/plugin-agent-federation/src/`
Tests	`v3/@claude-flow/plugin-agent-federation/__tests__/`
ADRs	`v3/docs/adr/ADR-{097,104,105,106,107,109,110,111}-*.md`
Phase 7 staging script	`v3/@claude-flow/plugin-agent-federation/scripts/phase7-stage.mjs`
Witness signing	`plugins/ruflo-core/scripts/witness/`

Releases

Version	What landed
`1.0.0-alpha.9`	First user-visible release — see announcement gist
`1.0.0-alpha.10`	ADR-097 Phases 2.a-4 + ADR-104 transport + ADR-109 inbound dispatcher
`1.0.0-alpha.11-12`	ADR-109 sig verify, ADR-104 compression, ADR-107 TLS cert pinning
`1.0.0-alpha.13`	ADR-104 stream multiplexing + ADR-110 MemorySpendReporter
`1.0.0-alpha.14`	ADR-111 Phases 1-3 (WG mesh foundation)
`1.0.0-alpha.15` (in flight)	ADR-111 Phases 4-6 (firewall + witness + MCP tools) — PR #1895

Related ADRs

ADR-097 — budget + circuit breaker
ADR-104 — WSS transport + multiplexing
ADR-105 — state snapshot/replay
ADR-106 — discovery mechanisms
ADR-107 — TLS + cert pinning
ADR-109 — inbound dispatch + sig verify
ADR-110 — production SpendReporter
ADR-111 — WG mesh layer

Support

Issues: https://github.com/ruvnet/ruflo/issues
Tracking issue (ADR-111): #1879
Federation gist (current through alpha.14): https://gist.github.com/ruvnet/3b5111a2ea7e450ff262ce96e88560bf
ADR-111 deep-dive gist: https://gist.github.com/ruvnet/c640fc71c7a6ced37908e645d5db84c5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

Ruflo Federation — User Guide

What federation does

When to use federation

Quick start

1. Install the plugin

2. Initialize a node

3. Join a peer

4. Send a message

MCP tools at a glance

Trust levels — what each unlocks

Circuit breaker

ADR-111 — WireGuard mesh (opt-in, since alpha.14)

Enabling ADR-111

Using `claude -p` headless mode

Anti-goals — when NOT to use federation

Where things live

Releases

Related ADRs

Support

FilesExpand file tree

federation

Directory actions

More options

Directory actions

More options

Latest commit

History

federation

Folders and files

parent directory

README.md

Ruflo Federation — User Guide

What federation does

When to use federation

Quick start

1. Install the plugin

2. Initialize a node

3. Join a peer

4. Send a message

MCP tools at a glance

Trust levels — what each unlocks

Circuit breaker

ADR-111 — WireGuard mesh (opt-in, since alpha.14)

Enabling ADR-111

Using claude -p headless mode

Anti-goals — when NOT to use federation

Where things live

Releases

Related ADRs

Support

Using `claude -p` headless mode