vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(nix): require swarm.domain and hiveName

Browse source 
Neither has a fallback worth having: a guessed swarm domain is a wrong
hostname that evaluates cleanly and deploys, which is worse than an
eval failure naming the one line an operator has to write. Upgrading
past this sets both, once.

Requiring them also makes the hive domain fully derived rather than
merely derivable — `<hiveName>.<swarm.domain>` now always resolves, so
an operator writes the swarm's address and this hive's label and never
writes the hive domain at all.

`hiveName` stops being display-only in the process: it is the leftmost
label of the domain the hive is addressed by, which the option text and
docs now say.

Each of the three required options asserts separately, so a missing one
names itself. A missing `swarm.domain` legitimately fails two of them —
its own, and `domain`, which can no longer derive — and nix reports all
failing assertions together, so the operator sees the whole set rather
than one at a time.
This commit is contained in:
atlas 2026-08-05 15:07:11 +02:00 • committed by mara
commit fbf3757551
3 changed files with 63 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/swarm.md
View file

@ -19,31 +19,37 @@ the additional config needed when the swarm spans multiple hosts.
```nix
services.hyperhive = {
domain = "pr1ma.example.com"; # machine-addressable DNS domain
hiveName = "pr1ma"; # human display name (optional)
swarm.domain = "example.com"; # required — the swarm's DNS domain
hiveName = "pr1ma"; # required — this hive's label in it
# domain = "pr1ma.example.com"; # derived from the two above
swarm.name = "constellat1on"; # shared swarm display name (optional)
swarm.domain = "example.com"; # the swarm's DNS domain
};
```
`domain` is required whenever hyperhive is enabled — eval fails with a
hint if it is unset. It drives `HYPERHIVE_HIVE_DOMAIN` in every
container so agents can form qualified labels
(`iris@pr1ma.example.com`).
`swarm.domain` and `hiveName` are **required** whenever hyperhive is
enabled; eval fails with a hint naming each. Neither is defaulted,
because a guessed value here is a wrong hostname that evaluates cleanly
and deploys — an eval failure asking the operator to write the address
down is the cheaper outcome. **Upgrading past this release means setting
both once.**
You can also *not* write it: with `swarm.domain` and `hiveName` set,
`domain` defaults to `<hiveName>.<swarm.domain>`, since every hive in a
swarm occupies its own sub-domain of it. That is a default and not a
rename — a hive that pins `domain` explicitly keeps exactly the value it
has today, which is the point: re-rooting where a value *comes from*
must not reinterpret the values already deployed.
`domain` is required too, but you no longer have to *write* it: it
defaults to `<hiveName>.<swarm.domain>`, since every hive in a swarm
occupies its own sub-domain of it. A hive that pins `domain` explicitly
keeps exactly the value it has today — that's why this is a default and
not a rename: re-rooting where a value *comes from* must not reinterpret
the values already deployed.
`hiveName` and `swarm.name` are purely display — they surface in the
dashboard chrome header and per-agent system prompts. Federated hives
at different domains can share a `swarm.name`; that it sits under
`swarm` and
`hiveName` does not is the whole distinction — one names this hive, the
other names the group it belongs to.
`domain` drives `HYPERHIVE_HIVE_DOMAIN` in every container so agents can
form qualified labels (`iris@pr1ma.example.com`).
`swarm.name` is purely display — it surfaces in the dashboard chrome
header and per-agent system prompts, and federated hives at different
domains can share one. `hiveName` surfaces in the same places but is
*not* only display: it is the leftmost label of the hive's domain. That
`swarm.name` sits under `swarm` and `hiveName` does not is the whole
distinction — one names this hive, the other names the group it belongs
to.
See `docs/conventions.md` § Hive identity for the env-var chain
and `qualify()` / `qualified_label()` semantics.