Watch

iris 0e99662710 docs: the swarm README and credentials page keep the overview, the rest moves to its own pages

The hive directory and the WireGuard mesh become handbook pages of their own,
the controller's mint-failure handling moves to controller.md, and the
credential-by-credential mechanics and the secret store UI's proxy move to a new
implementation page.

2026-11-14 13:33:50 +01:00

2.6 KiB

Raw Blame History

WireGuard mesh between hives (optional)

The peer config in the hive directory uses public HTTPS for all inter-hive traffic. For private deployments — or to reduce latency and TLS overhead on intra-swarm traffic — hyperhive can configure a host-to-host WireGuard mesh.

Generating keys

On each hive host:

wg genkey | install -m 0400 /dev/stdin /etc/wireguard/hive.key
wg pubkey < /etc/wireguard/hive.key   # → share this with peer operators

Config example (two hives)

# hive A (firsthive.myswarm.example, mesh IP 10.100.0.1)
services.hyperhive = {
  deploy.wireguard = {
    enable = true;
    privateKeyFile = "/etc/wireguard/hive.key";
    address = "10.100.0.1/24";
    listenPort = 51820; # optional, default 51820
  };

  # The same `hives` attrset both hosts hold — mesh fields included,
  # since "where this hive can be dialled" is a fact about that hive.
  swarm.hives = {
    firsthive = {
      domain = "firsthive.myswarm.example";
      wireguardPublicKey = "base64keyA=";
      wireguardEndpoint = "198.51.100.1:51820";
      wireguardAddress = "10.100.0.1/32";
    };
    secondhive = {
      domain = "secondhive.elsewhere.example";
      wireguardPublicKey = "base64keyB=";
      wireguardEndpoint = "203.0.113.42:51820";
      wireguardAddress = "10.100.0.2/32";
    };
  };
};

# hive B (secondhive.elsewhere.example, mesh IP 10.100.0.2)
services.hyperhive = {
  deploy.wireguard = {
    enable = true;
    privateKeyFile = "/etc/wireguard/hive.key";
    address = "10.100.0.2/24";
  };

  swarm.hives = {
    # … identical to hive A's …
  };
};

What the mesh does

hyperhive configures networking.wireguard.interfaces.wg-hive on the host (not inside agent containers; containers reach peers via the host's routing table).
It opens UDP port 51820 (or listenPort) on the host firewall.
It reads each entry's wireguardAddress from services.hyperhive.swarm.hives, minus this host's own hive, to build wg-hive's allowedIPs, so intra-swarm traffic can route over the mesh address rather than the public domain.
It sets persistentKeepalive = 25 by default; override or null to disable (not needed when both sides have public IPs and no NAT).

NAT / one-sided endpoints

If one host is behind NAT and can't accept incoming connections, only that host needs a null wireguardEndpoint on the peer config — the other side initiates. With keepalive on, the NAT hole stays open.

If both hosts are behind NAT, you need a STUN relay or a third host (exit node); hyperhive sets up neither.

2.6 KiB Raw Blame History