Mesh & Federated Network

PiSovereign can connect with other PiSovereign instances on your local network to share computing power and collectively improve AI quality — all while keeping your data private.

Two Features, One Network

The mesh network provides two complementary capabilities:

FeatureWhat It DoesPrivacy
Mesh InferenceBorrow a peer’s GPU/NPU when yours is busy or overheatingYour query goes to the peer encrypted; only the response comes back
Federated LearningShare model improvements (LoRA weight deltas) between peersDifferential privacy noise added before sharing — peers can’t recover your data

Both features share the same peer discovery and trust infrastructure.

Setting Up

1. Enable the Features

In config.toml on each PiSovereign instance:

[mesh]
enabled = true
discovery = "mdns"          # Automatic LAN discovery
serve_inference = true      # Allow peers to use your compute
max_concurrent_peer_requests = 2
request_timeout_secs = 60

[federated_learning]
enabled = true
sync_after_n_samples = 5    # Sync after every 5 training samples
max_peers = 10
noise_epsilon = 1.0         # Differential privacy noise level
aggregation_method = "fedavg"

2. Pair Your Instances

Peers must be manually approved — there is no automatic trust. Two methods:

  1. On Instance A: Generate a pairing code from Settings → Network → Generate Pairing Code
  2. On Instance B: Enter the code in Settings → Network → Add Peer
  3. Both instances confirm the pairing

QR Code

  1. On Instance A: Display QR code from Settings → Network
  2. On Instance B: Scan the QR code (if the device has a camera)

3. Verify Connection

After pairing, the Settings → Network page shows connected peers with:

  • Peer name and IP address
  • Connection status (🟢 Connected / 🔴 Offline)
  • Available models on the peer
  • Last sync timestamp (for federated learning)

How Mesh Inference Works

When you send a message and your local Ollama is busy, overloaded, or throttled due to heat:

Your Query
    │
    ▼
Local Ollama ──(busy/hot)──► Peer Ollama ──(unavailable)──► Cached Response
    │                              │                              │
    ▼                              ▼                              ▼
  Response                      Response                    Degraded Response
  (normal)                   (⚡ Mesh-assisted)            (from template)

The fallback chain:

  1. Local Ollama — always tried first
  2. Peer Ollama — lowest-latency peer with the requested model, E2E encrypted
  3. Cached response — from semantic cache if a similar query was answered before
  4. Template response — generic acknowledgment (“I’m currently limited, but here’s what I know…”)

What Gets Sent to Peers

  • Your query text (encrypted with the peer’s public key)
  • The requested model name
  • Nothing else — no conversation history, no memories, no user profile

How Federated Learning Works

After your PiSovereign collects 5 new training samples (from your feedback — thumbs up/down, corrections):

  1. Local training: LoRA adapter weights are updated locally
  2. Privacy noise: Laplace noise (ε = 1.0) is added to the weight deltas
  3. Encrypted sync: Noisy deltas are encrypted and sent to each trusted peer
  4. FedAvg aggregation: Each peer averages the received deltas with their own
  5. Privacy budget: The sync operation consumes ε from your formal privacy budget

What gets shared:

  • LoRA weight deltas (small numeric arrays) with differential privacy noise
  • Not shared: Your conversations, memories, personal data, or training samples

Think of it like this: You’re sharing “the AI got a bit better at this type of question” without sharing what the question was.

Discovery

mDNS (Default)

PiSovereign uses multicast DNS (mDNS/Avahi) for zero-configuration discovery on the local network. This means:

  • LAN only — peers must be on the same network segment
  • No internet required — everything stays local
  • Automatic — new instances appear in the peer list without manual IP entry

Requirements

  • mDNS/Avahi must be available (installed by default on most Linux distributions and Raspberry Pi OS)
  • UDP port 5353 must not be blocked by local firewall
  • Devices must be on the same subnet

Security

LayerProtection
DiscoverymDNS on LAN only — not routable over the internet
TrustManual peer approval with shared secret — no automatic trust
TransportmTLS (mutual TLS) — both sides verify certificates
PayloadPer-request encryption with peer’s public key
PrivacyDifferential privacy noise on all federated weight updates
BudgetFederated syncs consume privacy budget (ε) — stops when exhausted

Troubleshooting

Peers Not Discovered

  1. Verify both instances are on the same subnet
  2. Check that mesh.enabled = true in both config files
  3. Test mDNS: avahi-browse -a should show PiSovereign services
  4. Check firewall: UDP 5353 must be open

Mesh Inference Slow

  1. Check peer’s thermal state — it may be throttling
  2. Verify the peer has the requested model downloaded
  3. Try increasing request_timeout_secs
  4. Check network latency: ping <peer-ip>

Federated Sync Not Working

  1. Verify federated_learning.enabled = true on both peers
  2. Check privacy budget — syncs pause when budget is exhausted
  3. Ensure at least sync_after_n_samples training samples have been collected
  4. Check logs: docker logs pisovereign 2>&1 | grep federated

See Also