103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```nix
|
|
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
|
|
|
|
```nix
|
|
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
|
|
|
|
1. **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.
|
|
|
|
2. **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`).
|
|
|
|
3. **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
|