DocumentationRUN A FEDERATION NODE

RUN A FEDERATION NODE

Operate a sovereign node.

A federation node participates in cross-device immunity gossip without ever seeing raw user data. Optional — but the more nodes, the more decentralized the network.

01

What a node does

A node receives hashed-pattern broadcasts from devices in its region, runs the quorum protocol with peer nodes, and rebroadcasts confirmed patterns to its connected devices. It never receives or stores anything that identifies a user.

Privacy by construction
The protocol layer carries SHA-256 hashes and broad region buckets only. There is no code path for a node to receive an IP, an email, or a GPS coordinate. That is enforced by an automated test that fails the build if the boundary is breached.
02

Hardware requirements

A node is a Rust daemon plus a PostgreSQL 16 instance. Minimum:

  • 4 vCPU, 16 GB RAM, 200 GB SSD
  • Reliable connectivity, public reachable port (8443 by default)
  • YubiHSM 2 or equivalent for peer-identity key (recommended)
  • Time-synced (NTP) — the quorum protocol is sensitive to clock skew
03

Install

shell# 1. PostgreSQL 16 (skipped if you already have one)
sudo apt-get install -y postgresql-16

# 2. The federation daemon
curl -L -o lydos-fed-2026.06.r1.tar.gz \
  https://git.lydos.ailydian.com/lydos/sovereign-federation/releases/2026.06.r1/lydos-fed.tar.gz
curl -L -o release.manifest.json \
  https://git.lydos.ailydian.com/lydos/sovereign-federation/releases/2026.06.r1/release.manifest.json

# 3. Verify the bundle (the same protocol as the phone image)
./verify-bundle.sh --bundle lydos-fed-2026.06.r1.tar.gz --manifest release.manifest.json
# expects: signatures 3 / 3, hash match

# 4. Install
sudo tar -xzf lydos-fed-2026.06.r1.tar.gz -C /opt/lydos-fed
sudo /opt/lydos-fed/install.sh
04

Peer-identity key ceremony

The node’s peer-identity key signs every broadcast it emits. Generate it inside the YubiHSM under an M-of-N officer ceremony. Three officers, two-of-three to sign new keys. Document the ceremony in your internal log.

shell/opt/lydos-fed/bin/lydos-fed key generate --hsm yubihsm \
  --slot 1 --label fed-peer-2026.06 \
  --officers 2-of-3
Hot key warning
Do not generate this key on a workstation. The private half must never appear in any process memory you do not control. The HSM enforces this.
05

Join the peer registry

shell# Submit your node's public identity to the registry
/opt/lydos-fed/bin/lydos-fed join \
  --registry https://registry.lydos.ailydian.com \
  --pubkey-path /opt/lydos-fed/keys/fed-peer-2026.06.pub

The registry signs your entry and rebroadcasts it. Other nodes will reach out and complete the handshake. Typical onboarding takes 10–30 minutes.

06

Monitoring

The daemon exposes Prometheus metrics on /metrics and a JSON health snapshot on /health. Hook it into your existing dashboard or query it directly.

shellcurl https://your-node.example/health
# {
#   "version": "2026.06.r1",
#   "peers_online": "11/11",
#   "quorum": "ok",
#   "audit_chain_head": "3571a6c8…",
#   "uptime_seconds": 123456
# }
07

Backup and restore

The PostgreSQL volume is the only stateful component you need to back up. The keys live in the HSM and are reconstructible only by ceremony. The daemon configuration is reproducible from /etc/lydos-fed.

Restoring is fast
A fresh node joins the federation, asks peers for the current chain head, and catches up. The longest catch-up we have observed in production is 18 minutes from cold start to in-quorum.