Multi-hive swarms

A swarm is a collection of agents that share an identity and coordinate across one or more hives. A single hyperhive instance running on one host is already a swarm (one hive). This doc covers the additional config needed when the swarm spans multiple hosts.

Terminology

hive — a single hyperhive installation on one host. Has its own services.hyperhive.domain DNS name and its own set of agent containers.
swarm — one or more hives whose operators have declared them as peers. Agents can be qualified as agent@hive-domain.
peer hive — a remote hive declared under services.hyperhive.swarm.peers on the local host.

Hive identity config

services.hyperhive = {
  domain   = "pr1ma.example.com";   # machine-addressable DNS domain
  hiveName  = "pr1ma";              # human display name (optional)
  swarmName = "constellat1on";      # shared swarm display name (optional)
};

domain is required when matrix federation is on (matrix.enable); it drives HYPERHIVE_HIVE_DOMAIN in every container so agents can form qualified labels (iris@pr1ma.example.com). hiveName and swarmName are purely display — they surface in the dashboard chrome header and per-agent system prompts. Federated hives at different domains can share a swarmName.

See docs/conventions.md § Hive identity for the env-var chain and qualify() / qualified_label() semantics.

Declaring peer hives

services.hyperhive.swarm.peers = {
  "lab.example.com"  = { };                               # CA-trusted (Let's Encrypt etc.)
  "edge.corp"        = { certFingerprint = "sha256:…"; }; # self-signed TLS
};

The attrset key is the peer's DNS domain. certFingerprint is optional:

Omitted / null — the system CA bundle validates the peer's TLS cert. Correct for peers with Let's Encrypt or any standard CA cert.
Set ("sha256:…") — pin a specific cert fingerprint. Use this for peers whose self-signed TLS cert doesn't chain to a CA your host trusts.

The nix module serialises the attrset to a HYPERHIVE_PEERS JSON array ([{ domain, cert_fingerprint }]) injected into the c0re environment and forwarded to agent containers.

What the config does at runtime

Dashboard P33RS tab — parse_peer_hives() in dashboard.rs reads HYPERHIVE_PEERS and includes peer_hives: Vec<{ name, url }> in /api/state. The dashboard shows a P33RS tab (hidden when the list is empty) with a card per peer linking to https://{domain}/. See docs/web-ui/dashboard.md § P33RS tab.
Agent identity — identity::peers() in hive-ag3nt reads the same env var and exposes the peer list to agents via get_agent_meta so agents can address peers with qualified names (agent@peer-domain).
Matrix federation — when matrix.enable is on, tuwunel federates with the peer's matrix server at matrix.{peer-domain}:8448. No extra config needed; federation works as soon as the domains are reachable and TLS validates. See docs/matrix.md for federation firewall requirements.

Bilateral setup

Each hive must declare the other. If hive A lists hive B as a peer, B must also list A for agents on B to see A in their peer list:

# hive A (pr1ma.example.com)
services.hyperhive.swarm.peers."edge.corp" = { };

# hive B (edge.corp)
services.hyperhive.swarm.peers."pr1ma.example.com" = { certFingerprint = "sha256:…"; };

Mixed trust is fine: A trusts B via CA bundle (no fingerprint), B pins A's self-signed cert.

Cross-references

docs/conventions.md § Hive identity — env vars, qualified labels
docs/matrix.md — matrix federation, TLS cert auto-generation, firewall posture
docs/web-ui/dashboard.md § P33RS tab — dashboard surface
docs/gateway.md — nginx vhosts and the .well-known/matrix/ auto-discovery scheme

3.8 KiB Raw Blame History