Federation

Overview

mycellm supports multiple independent networks. Each network has its own bootstrap node, trust policy, and credit ledger. Nodes can join several networks simultaneously, and gateway nodes bridge traffic between them.

Network identity

Every network is defined by a NetworkMembership record:

Field	Description
id	SHA256 of bootstrap’s account public key
name	Human-readable network name
bootstrap	Address of the network’s bootstrap node
trust_level	strict, relaxed, or honor
fleet_key	Ed25519 public key for fleet administration

# List joined networks
mycellm network list

Creating a private network

Any node running in bootstrap mode can create a network:

mycellm bootstrap init --name "my-org" --trust strict

This generates:

• A network identity (derived from the bootstrap’s account key)
• A fleet admin key for managing nodes remotely
• An invite endpoint at /federation/invite

Invite tokens

Invite tokens are portable base64-encoded blobs signed with the bootstrap’s Ed25519 key:

# Generate an invite (bootstrap node)
mycellm network invite --max-uses 10 --expires 7d

# Output: mcl_invite_eyJuZXR3b3JrIjoiYTFiMmMz...

The token contains:

• Network ID and bootstrap address
• Max uses and expiry timestamp
• Ed25519 signature from the bootstrap key

Join with an invite:

mycellm network join mcl_invite_eyJuZXR3b3JrIjoiYTFiMmMz...

The node verifies the signature, connects to the bootstrap, and registers as a member.

Multi-network membership

Since 0.6.0, a node can belong to multiple networks simultaneously — e.g. serve the public network while also participating in a private one. Each node announces its network memberships in the NodeHello handshake, and routing respects network isolation end-to-end: a request is only ever routed to peers that share at least one network with the requester. Peers that declare no networks are treated as public, so single-network deployments and older peers keep working unchanged.

Models can also be scoped per network: advertise a model to your home network only, to an explicit list of networks, or to everyone.

Hosting a private network

Since 0.6.1, a node can also host additional networks — no separate coordinator process needed. One mycellm serve on the standard QUIC port participates in the public network and acts as the bootstrap for your private ones:

# Host a new private network from this node
mycellm network host my-lab

# See everything this node hosts or belongs to
mycellm network list

# Invite a device (signed token, works with `mycellm init --invite`)
mycellm network invite --network <id-prefix> --max-uses 5 --expires-hours 168

# Stop hosting
mycellm network drop <id-prefix>

Hosted network identities live in federation/hosted/ and are advertised in the node’s NodeHello; the running node picks up changes on restart. Members connect to the host’s normal QUIC endpoint (port 8421 by default).

Two things to know:

• Home-scoped models are visible to networks you host. Members you invite can use your local models; the public network still cannot. Use per-model scopes for finer control.
• Migrating from a standalone coordinator: mycellm network host --import path/to/network.json preserves the network id, so existing members only need to re-point their bootstrap endpoint at the node.

Since 0.6.2, a hosted network can require a join key: set one with mycellm network host <name> --join-key K (or mycellm network set-key <id-prefix> K on an existing network) and peers must present it in their NodeHello to be accepted into that network — claims without the key are dropped while the connection stays up for the peer’s other networks. Networks without a key behave as before. Members store the key on their membership and present it automatically.

Gateway nodes

A node that belongs to multiple networks can act as a gateway, bridging inference requests between them:

Network A                          Network B
    │                                  │
    ├── Node 1                         ├── Node 4
    ├── Node 2                         ├── Node 5
    └── Node 3 (gateway) ◀──────────▶ Node 3 (gateway)

Gateway behavior is automatic. When a model is unavailable in the requesting network, the gateway checks its other networks for providers. Cross-network requests carry both network IDs so credit accounting stays correct.

# Enable gateway mode (must be member of 2+ networks)
mycellm config set federation.gateway true

Credit ledgers

Each network maintains its own credit ledger. Credits do not transfer between networks. A node that serves inference in Network A earns credits in Network A’s ledger.

# View per-network balances
mycellm credits --by-network

Gateway-bridged requests debit the consumer’s ledger in their home network and credit the provider’s ledger in the provider’s network. The gateway node earns a routing fee in both.

Fleet management

The fleet admin key allows remote management of all nodes in a network via FLEET_COMMAND messages:

# Send a fleet command (requires admin key)
mycellm fleet reload-config --network my-org
mycellm fleet update-model --network my-org --model llama-3.2-3b-q4_k_m

Fleet commands are signed with the admin key and verified by each node before execution. Supported commands:

Command	Description
reload-config	Reload node configuration
update-model	Pull or remove a model
set-policy	Update privacy or trust settings
drain	Stop accepting new requests (graceful shutdown)
status	Report node status back to admin

Trust levels

Trust levels control verification behavior across the network:

Level	Behavior
strict	Verify device certs + enforce Privacy Guard + validate credit signatures
relaxed	Verify device certs + log Privacy Guard violations (don’t block)
honor	Skip cert verification and Privacy Guard (trusted LAN environments)

Set per-network:

mycellm network set-trust my-org strict