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

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

Trust levels — what each unlocks

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

Releases

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