iN2N Federation: 'A Risk of NetClaws' and the NCFED Protocol

The collective noun for lobsters is "a risk," so NetClaw's federation feature stakes its whole identity on a pun: instead of running one monolithic claw that hoards every capability, an operator runs a risk of NetClaws — a coordinating Border Claw fronting a school of focused member claws. The design borrows its vocabulary wholesale from the Border Gateway Protocol and inter-autonomous-system routing. The Border is the single externally visible face of the risk, exactly as an AS border router (or a confederation identifier) presents one AS to the outside while hiding sub-ASes within. "iN2N" reads as internal network-to-network, the intra-risk coordination that parallels iBGP, while its sibling eN2N covers external federation between separate operators, paralleling eBGP between distinct autonomous systems. The wire protocol that carries all of it is NCFED, the N2N Federation Protocol, published as an IETF Internet-Draft. What follows treats the README as authoritative on every number.

Border Claw, Member Claws, and the Token Economy

A monolithic NetClaw is a ~194-skill instrument. Loading that whole surface into every turn also drags in 37–52 MCP servers, producing hundreds-to-thousands of tool schemas in context before the model has read a single word of the user's request. Federation attacks this directly. The Border carries zero domain skills and only ~32 broker tools — it exists to understand the request, pick a member, and route. Each member holds ~3 specialty skills and nothing else: a pyATS claw for device automation, a CML claw for lab topologies, an Azure claw for cloud work. The result the README claims is a 15–30x reduction in per-claw tool-schema context, because no single process ever again sees the full ~194-skill catalog. This is the "narrow context per worker" mechanism from the multi-agent federation literature made concrete — the orchestrator attaches only the minimum context each subtask needs, and the school as a whole moves from "one agent with one huge, noisy context" to "many agents, each with a small focused one."

Federation also unlocks tiered models. Reasoning-heavy routing runs an Opus-class Border, while members run cheaper tiers — Sonnet, Haiku, or a local Ollama model — matched to their narrow jobs.

Least-privilege secret slicing is the security dividend of that same narrowing. Each member receives only its own integration's credentials. A pyATS member is handed PYATS_CONNECTION_* and nothing more — it never sees AWS_ACCESS_KEY_ID. The operator's master .env is held out of member processes entirely by a kernel sandbox, so a compromised or confused member cannot exfiltrate credentials for a domain it has no business touching. Task assignment itself encodes the privilege boundary: a member that lacks a secret is simply never routed work that needs it.

One door, one audit trail. The Border is the sole external interface, the risk's identity, and its single audit point. Members dial outbound to the Border — no ngrok tunnels, no service mesh, no inbound ports to expose. That means members function identically whether co-located on one host or scattered across clouds, and every request that enters or leaves the risk passes one chokepoint that can be logged. Production mode adds append-only GAIT git audit trails on both Border and members under ~/.openclaw/n2n/gait/.

flowchart TD
    User["External request"] --> Border["Border Claw (Opus, ~32 broker tools, 0 skills)"]
    Border --> GAIT["GAIT audit trail (one chokepoint)"]
    pyATS["pyATS member (Sonnet, PYATS_CONNECTION_* only)"] -.->|"outbound grpc :50051"| Border
    CML["CML member (Haiku, CML lab secrets only)"] -.->|"outbound grpc :50051"| Border
    Azure["Azure member (Ollama, AZURE creds only)"] -.->|"outbound grpc :50051"| Border
    Border -->|"routes task"| pyATS
    Border -->|"routes task"| CML
    Border -->|"routes task"| Azure

Install Roles and Setup

At install time the operator chooses one of three roles:

• standalone — a single NetClaw that acts as its own Border (the default, non-federated deployment).
• Border — coordinates member claws.
• Member — joins a risk under an existing Border.

The role is selected via OPENCLAW_N2N_MODE, after which openclaw onboard runs the interactive setup. A Border needs only its mode; a member additionally needs the Border's gRPC endpoint so it knows where to dial outbound.

# Border
export OPENCLAW_N2N_MODE=border
openclaw onboard

# Member
export OPENCLAW_N2N_MODE=member
export OPENCLAW_N2N_BORDER_URL=grpc://border-claw.example.com:50051
openclaw onboard

Hardened operation is gated behind two more variables. N2N_RISK_MODE=production enforces fail-closed controls — the hardened systemd member sandbox (NoNewPrivileges, ProtectSystem=strict, private /tmp, syscall and namespace limits), the DefenseClaw model-guard proxy on :4000, and the GAIT audit trails. Its "honest posture" refuses to falsely claim enforcement, flagging audit-degraded when a control is missing rather than pretending it is on. N2N_STRICT_ALL=1 hardens this further, blocking on any control gap.

# Production enforcement (fail-closed) with certificates
export N2N_RISK_MODE=production
export N2N_CERT_MODE=enforce
./scripts/patch-claw-certs.sh   # upgrade existing claws; auto-rotates credentials

NCFED: The Wire Protocol and Certification

The over-the-wire protocol is specified in the IETF Internet-Draft draft-capobianco-ncfed-00, marked Experimental. It uses BGP-multiplexed discrimination, a 13-octet handshake, and framing, and it carries both the eN2N (external, between operators) and iN2N (internal risk) consent models. The BGP lineage is deliberate: where BGP speakers run a six-state finite state machine over TCP 179 and exchange OPEN/KEEPALIVE messages to reach the Established state, NCFED's multiplexed handshake is the playful analogue, and its eN2N/iN2N split maps onto eBGP-between-ASes versus the intra-confederation relationship.

sequenceDiagram
    participant M as Member Claw
    participant B as Border Claw (risk CA)
    M->>B: Outbound dial grpc :50051
    M->>B: 13-octet handshake (BGP-multiplexed discrimination)
    B-->>M: Present Border certificate
    M->>B: Present member certificate (mutual auth)
    B-->>M: Verify and issue auto-rotating credentials
    M->>B: Channel Established (consent model iN2N or eN2N)

Claw Certification (feature 060) closes the crypto gap so federation channels use TLS encryption and certificate authentication rather than plaintext trust. Two trust models are offered, matching the classic PKI-versus-first-contact tradeoff:

• Domain-verified — ACME / Let's Encrypt issuance via the DNS-01 challenge, binding a claw's identity to a domain the operator actually controls. DNS-01 is the natural fit here: it needs no exposed HTTP endpoint and is the only challenge type that supports wildcards.
• Pinned self-signed — a TOFU (Trust On First Use) model, accepting the certificate seen on first contact and alerting on any later change, exactly as SSH host-key verification does. It needs no external CA, at the cost of a vulnerable first connection — appropriate for internal risks where first contact can be verified out of band.

Certification is enabled with N2N_CERT_MODE=on|enforce, and existing claws are upgraded in place:

export N2N_CERT_MODE=on   # or 'enforce' to require certs
./scripts/patch-claw-certs.sh

The Border acts as its risk's CA, issuing and verifying member certificates the way an internal enterprise PKI would; members verify the hub in turn (mutual authentication) using auto-rotating credentials.

A standing caveat governs all of this: an IETF Internet-Draft has no formal status, "should not be cited in any formal document," and may never become an RFC. The -00 suffix marks the first, unadopted individual-submission revision. NCFED is experimental by its own declaration — expect breaking changes to the on-the-wire protocol before it reaches RFC. The README remains authoritative on the counts (~194 skills monolithic; Border ~32 broker tools and 0 domain skills; members ~3 skills each; the 15–30x context reduction).

References