vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

hyperhive: make the values the meta-flake render reads swarm-wide

Browse source 
Five host options whose values hive-c0re renders into every agent's
build move under services.hyperhive.swarm, so the swarm states each of
them once instead of every hive carrying its own copy:

  c0re.dashboardPort          -> swarm.dashboardPort
  c0re.claudeCodePackage      -> swarm.claudeCodePackage
  github.enable               -> swarm.github.enable
  otel.collector.port         -> swarm.hiveOtel.collectorPort
  otel.extraResourceAttributes -> swarm.hiveOtel.extraResourceAttributes

Every old path is a mkRenamedOptionModule alias, so a host that sets one
keeps its value and gets an eval warning naming the new path. Types and
defaults are unchanged, so the rendered meta flake, serve.json and
hive-c0re's environment are the same as before on a host that sets
none of them.

The readers move with them: serve.json and its gc-root assertion, the
hive-c0re environment, the hive collector's listen address and bridge
port, the swarm collector's port-collision assertion, and the
claude-login and review-classifier containers' claude pin. The
swarm-services-switch fixture sets the swarm path and now also checks
that serve.json carries the pinned claude.

Part of #4857 (slice 2).
This commit is contained in:
atlas 2026-10-16 03:31:45 +02:00 • committed by mara
commit fc32f57481
25 changed files with 189 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

6
nix/agent-modules/default.nix
View file

@ -96,7 +96,7 @@ in
nixpkgs.
Set by the generated meta flake when the operator sets
`services.hyperhive.c0re.claudeCodePackage` host-side, so a hive
`services.hyperhive.swarm.claudeCodePackage` host-side, so a swarm
can run a claude built from a *different* nixpkgs than the one
its agents evaluate against — a release channel can trail
unstable by weeks on this one package. It arrives as a path and
@ -109,7 +109,7 @@ in
there is only ever one claude in the container. Note that neither
the symlink nor anything else in the container's closure *refers*
to the target — keeping it alive is the host's job, see
`services.hyperhive.c0re.claudeCodePackage`.
`services.hyperhive.swarm.claudeCodePackage`.
'';
};
@ -255,7 +255,7 @@ in
# The symlink registers no store reference — the target isn't
# among this derivation's inputs, so nothing here keeps the
# binary alive. That is deliberate and it is the host's job:
# see `services.hyperhive.c0re.claudeCodePackage`.
# see `services.hyperhive.swarm.claudeCodePackage`.
pkgs.runCommandLocal "claude-code-pinned" { } ''
mkdir -p "$out/bin"
ln -s ${config.services.hyperhive.agent.claudeCodePath}/bin/claude "$out/bin/claude"

4
nix/agent-modules/github.nix
View file

@ -55,8 +55,8 @@ in
a compromised agent can act within the token's scopes --- scope is the
real blast-radius limiter.
On by default. Host-driven: set `services.hyperhive.github.enable = false`
to turn the integration off hive-wide (meta.rs propagates the override
On by default. Host-driven: set `services.hyperhive.swarm.github.enable = false`
to turn the integration off swarm-wide (meta.rs propagates the override
into every agent).
'';
};

2
nix/agent-modules/otel.nix
View file

@ -125,7 +125,7 @@ in
Extra comma-separated entries appended to
`OTEL_RESOURCE_ATTRIBUTES` after the built-in
`service.name` / `agent` / `swarm` labels.
Host-driven via `services.hyperhive.otel.extraResourceAttributes`.
Host-driven via `services.hyperhive.swarm.hiveOtel.extraResourceAttributes`.
'';
};

10
nix/host-modules/hive-c0re/default.nix
View file

@ -12,6 +12,7 @@
}:
let
cfg = config.services.hyperhive.c0re;
swarmCfg = config.services.hyperhive.swarm;
# `/run/hyperhive`'s mode. Held in one place because whichever of the two
# units below activates first creates the directory, so they cannot be
@ -110,8 +111,8 @@ let
# anything that drops it. The failure mode is a garbage-collected
# `claude` and a hive that can't take a turn, weeks after the commit
# that caused it.
claude_code_path = cfg.claudeCodePackage;
dashboard_port = cfg.dashboardPort;
claude_code_path = swarmCfg.claudeCodePackage;
dashboard_port = swarmCfg.dashboardPort;
agent_cpu_quota = cfg.agentCpuQuota;
agent_memory_max = cfg.agentMemoryMax;
agent_cpu_weight = cfg.agentCpuWeight;
@ -163,9 +164,10 @@ in
# `claude`, at whatever unrelated moment the gc runs. Cheap
# enough to just check.
assertion =
cfg.claudeCodePackage == null || builtins.hasContext (builtins.toJSON cfg.claudeCodePackage);
swarmCfg.claudeCodePackage == null
|| builtins.hasContext (builtins.toJSON swarmCfg.claudeCodePackage);
message = ''
services.hyperhive.c0re.claudeCodePackage lost its store
services.hyperhive.swarm.claudeCodePackage lost its store
context on the way into /etc/hyperhive/serve.json, so the
package is no longer gc-rooted by the system closure and
`nix-collect-garbage` may delete the claude every agent runs.

18
nix/host-modules/hive-c0re/environment.nix
View file

@ -65,27 +65,29 @@ in
// lib.optionalAttrs (config.services.hyperhive.swarm.name != null) {
HYPERHIVE_SWARM_NAME = config.services.hyperhive.swarm.name;
}
// lib.optionalAttrs (!config.services.hyperhive.github.enable) {
// lib.optionalAttrs (!config.services.hyperhive.swarm.github.enable) {
# GitHub integration is on by default; only signal the OFF override to
# meta.rs, which then injects `services.hyperhive.agent.github.enable = false` into
# every agent. See services.hyperhive.github.enable.
# every agent. See services.hyperhive.swarm.github.enable.
HYPERHIVE_GITHUB_DISABLED = "1";
}
// lib.optionalAttrs config.services.hyperhive.otel.enable (
# Hive-wide OTEL config -> read by meta.rs::otel_config and
# injected as build-time `services.hyperhive.agent.otel.*` into every agent.
# OTEL config (`swarm.hiveOtel`, gated on this hive's `otel.enable`) ->
# read by meta.rs::otel_config and injected as build-time
# `services.hyperhive.agent.otel.*` into every agent.
# Endpoint presence is the enable signal on the meta side; the
# optional fields are only emitted when set so absent values
# don't render no-op env lines.
let
otel = config.services.hyperhive.otel;
hiveOtel = config.services.hyperhive.swarm.hiveOtel;
# The first hop, this hive's own collector, under the two spellings its
# two kinds of caller need. Agents get the swarm-wide name, so their
# builds carry nothing hive-specific; this daemon gets the bridge
# address, because on the host the name may resolve to loopback
# (`gateway.localHostsEntry`), where the receiver does not listen.
agentFirstHop = "http://${otel.collector.host}:${toString otel.collector.port}";
hostFirstHop = "http://${config.services.hyperhive.network.bridgeIp}:${toString otel.collector.port}";
agentFirstHop = "http://${otel.collector.host}:${toString hiveOtel.collectorPort}";
hostFirstHop = "http://${config.services.hyperhive.network.bridgeIp}:${toString hiveOtel.collectorPort}";
in
{
# `otel.endpoint` means "where telemetry ultimately goes" and keeps
@ -113,8 +115,8 @@ in
# what has to honour it (see nix/host-modules/otel.nix).
HYPERHIVE_OTEL_PROTOCOL = "http/protobuf";
}
// lib.optionalAttrs (otel.extraResourceAttributes != "") {
HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES = otel.extraResourceAttributes;
// lib.optionalAttrs (hiveOtel.extraResourceAttributes != "") {
HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES = hiveOtel.extraResourceAttributes;
}
# HYPERHIVE_OTEL_HEADERS_CREDENTIAL is deliberately NOT emitted, and
# its absence is the security half of this design: that variable would

119
nix/host-modules/hive-c0re/options.nix
View file

@ -3,17 +3,29 @@
# `nixosModules.default` wires to its own outputs (they carry no
# in-module defaults; see ../../../flake.nix). The read-only
# `servedFrontend` option lives in ./theme.nix with the stylix wiring
# that computes it.
# that computes it. The swarm-wide values the meta-flake render hands
# every agent are declared here too, under `services.hyperhive.swarm`.
{
pkgs,
lib,
...
}:
let
renamedToSwarm =
name:
lib.mkRenamedOptionModule
[ "services" "hyperhive" "c0re" name ]
[ "services" "hyperhive" "swarm" name ];
in
{
imports = [
(lib.mkRemovedOptionModule [ "services" "hyperhive" "c0re" "managerToplevel" ] ''
Every agent, ruth included, builds from `agentBaseToplevel`. Remove this definition.
'')
]
++ map renamedToSwarm [
"claudeCodePackage"
"dashboardPort"
];
options.services.hyperhive.c0re = {
@ -119,56 +131,6 @@
of the host's channel.
'';
};
claudeCodePackage = lib.mkOption {
type = lib.types.nullOr lib.types.package;
default = null;
example = lib.literalExpression "inputs.nixpkgs-unstable.legacyPackages.x86_64-linux.claude-code";
description = ''
The `claude-code` build every agent runs, or `null` (the
default) to leave each agent on the `claude-code` from its own
nixpkgs — i.e. whatever `nixpkgsFlake` resolves to.
This is the one binary the whole hive is built around, and it
moves fast enough that a release channel routinely trails
unstable by weeks on it. An agent cannot fix that for itself:
agents evaluate against the single nixpkgs hive-c0re injects,
so an `agent.nix` has no other tree to reach for. Set this from
a second nixpkgs in the host flake and every agent follows,
without moving the nixpkgs the rest of the container is built
from.
What travels into the container is the **store path**, not the
derivation: agents share the host's `/nix/store`, so the binary
and its full closure are already reachable there — nothing
needs rebuilding or copying. hive-c0re writes the path into
each agent's generated flake as a plain string literal (a bare
path fed to `lib.types.package` would run `builtins.storePath`,
which is illegal under pure evaluation) and the agent module
puts its `bin/` on the harness's PATH.
The flip side of a plain string is that nothing in the agent's
own closure refers to it, so the container cannot keep it
alive. The **host** does that instead: this package is
interpolated into `/etc/hyperhive/serve.json`, which puts it in
the host's system closure — so it is gc-rooted by the running
generation for exactly as long as that generation is the one
the agents were rendered from. The cost is that
`nix-collect-garbage` cannot reclaim an old `claude-code` until
every agent has been rebuilt past it and the old generations
are gone.
The swarm's `swarm-claude-login` and `swarm-review-classifier`
containers, where this host runs them, follow the same pin and
keep their own nixpkgs' `claude-code` when it is `null`. They are
not agents, so pinning an older build for an agent-side
regression pins them too.
'';
};
dashboardPort = lib.mkOption {
type = lib.types.port;
default = 7000;
description = "TCP port the hive-c0re dashboard listens on.";
};
preBuildAgentTemplates = lib.mkOption {
type = lib.types.bool;
default = false;
@ -377,4 +339,59 @@
'';
};
};
# What every agent in the swarm is handed through the meta-flake render,
# whichever hive builds it. Swarm-wide so that no hive's agents differ.
options.services.hyperhive.swarm = {
claudeCodePackage = lib.mkOption {
type = lib.types.nullOr lib.types.package;
default = null;
example = lib.literalExpression "inputs.nixpkgs-unstable.legacyPackages.x86_64-linux.claude-code";
description = ''
The `claude-code` build every agent runs, or `null` (the
default) to leave each agent on the `claude-code` from its own
nixpkgs — i.e. whatever `c0re.nixpkgsFlake` resolves to.
This is the one binary the whole swarm is built around, and it
moves fast enough that a release channel routinely trails
unstable by weeks on it. An agent cannot fix that for itself:
agents evaluate against the single nixpkgs hive-c0re injects,
so an `agent.nix` has no other tree to reach for. Set this from
a second nixpkgs in the host flake and every agent follows,
without moving the nixpkgs the rest of the container is built
from.
What travels into the container is the **store path**, not the
derivation: agents share the host's `/nix/store`, so the binary
and its full closure are already reachable there — nothing
needs rebuilding or copying. hive-c0re writes the path into
each agent's generated flake as a plain string literal (a bare
path fed to `lib.types.package` would run `builtins.storePath`,
which is illegal under pure evaluation) and the agent module
puts its `bin/` on the harness's PATH.
The flip side of a plain string is that nothing in the agent's
own closure refers to it, so the container cannot keep it
alive. The **host** does that instead: this package is
interpolated into `/etc/hyperhive/serve.json`, which puts it in
the host's system closure — so it is gc-rooted by the running
generation for exactly as long as that generation is the one
the agents were rendered from. The cost is that
`nix-collect-garbage` cannot reclaim an old `claude-code` until
every agent has been rebuilt past it and the old generations
are gone.
The swarm's `swarm-claude-login` and `swarm-review-classifier`
containers, where this host runs them, follow the same pin and
keep their own nixpkgs' `claude-code` when it is `null`. They are
not agents, so pinning an older build for an agent-side
regression pins them too.
'';
};
dashboardPort = lib.mkOption {
type = lib.types.port;
default = 7000;
description = "TCP port every hive's hive-c0re dashboard listens on.";
};
};
}

2
nix/host-modules/hive-gateway/options.nix
View file

@ -62,7 +62,7 @@ in
description = ''
TCP port the gateway proxies non-static requests to. Defaults
to `7000` (hive-c0re's out-of-the-box dashboard port). Operators
who change `services.hyperhive.c0re.dashboardPort` should set
who change `services.hyperhive.swarm.dashboardPort` should set
`upstreamPort` to match — kept as a hardcoded default rather
than a cross-reference to keep this module's options eval
independent of c0re's option tree shape.

2
nix/host-modules/hive-network.nix
View file

@ -29,7 +29,7 @@ let
networkBase = builtins.bitAnd (ipToInt cfg.bridgeIp) (4294967295 - hostCount + 1);
# Every switch that runs a hyperhive service on this host. Left out:
# `github.enable` (on by default, runs nothing by itself), the gateway's
# `swarm.github.enable` (on by default, runs nothing by itself), the gateway's
# and matrix's sub-features, and `allSwarmServices`/`singleHostSwarm`,
# which only take effect through the switches listed here.
anyServiceEnabled =

10
nix/host-modules/hyperhive.nix
View file

@ -17,6 +17,10 @@ in
ruth from the swarm dashboard like any other agent; a ruth container that
already exists keeps starting with the hive.
'')
(lib.mkRenamedOptionModule
[ "services" "hyperhive" "github" "enable" ]
[ "services" "hyperhive" "swarm" "github" "enable" ]
)
];
# Canonical hive DNS domain shared by every subsystem that needs a
@ -192,15 +196,15 @@ in
# the values it asserts. It is a deployment mode rather than a setting
# this module's options read, so it lives with its consequences.
options.services.hyperhive.github.enable = lib.mkOption {
options.services.hyperhive.swarm.github.enable = lib.mkOption {
type = lib.types.bool;
default = true;
example = false;
description = ''
Hive-wide switch for the per-agent GitHub integration (the `gh` CLI
Swarm-wide switch for the per-agent GitHub integration (the `gh` CLI
wrapper + git credential helper, per `services.hyperhive.agent.github.enable`). On by
default: every agent gets the integration, inert until an operator links
a PAT for it in the swarm UI. Set `false` to turn it off for the whole hive --- the
a PAT for it in the swarm UI. Set `false` to turn it off for the whole swarm --- the
meta-flake renderer (`hive-c0re/src/meta.rs`) then injects
`services.hyperhive.agent.github.enable = false` into every agent. Exposed to hive-c0re
as `HYPERHIVE_GITHUB_DISABLED` (set only when the integration is off).

70
nix/host-modules/otel.nix
View file

@ -57,6 +57,14 @@ in
hostUnit = true;
enable = config.services.hyperhive.otel.enable;
})
(lib.mkRenamedOptionModule
[ "services" "hyperhive" "otel" "collector" "port" ]
[ "services" "hyperhive" "swarm" "hiveOtel" "collectorPort" ]
)
(lib.mkRenamedOptionModule
[ "services" "hyperhive" "otel" "extraResourceAttributes" ]
[ "services" "hyperhive" "swarm" "hiveOtel" "extraResourceAttributes" ]
)
];
options.services.hyperhive.otel = {
@ -147,17 +155,6 @@ in
'';
};
extraResourceAttributes = lib.mkOption {
type = lib.types.str;
default = "";
example = "deployment.environment=prod";
description = ''
Extra comma-separated entries appended to
`OTEL_RESOURCE_ATTRIBUTES` after the built-in
`service.name` / `agent` / `hive` / `swarm` labels.
'';
};
collector.upstreamHeaderName = lib.mkOption {
type = lib.types.str;
default = "Authorization";
@ -178,21 +175,6 @@ in
'';
};
collector.port = lib.mkOption {
type = lib.types.port;
default = 4318;
description = ''
Port the collector's OTLP/HTTP receiver listens on, at
`services.hyperhive.network.bridgeIp`. 4318 is the OTLP/HTTP
default.
The port is contributed to
`services.hyperhive.network.exposeHostPorts`, which opens it on
the bridge interface only — so it is reachable from agent
containers and not from the outside world.
'';
};
collector.host = lib.mkOption {
type = lib.types.str;
readOnly = true;
@ -296,14 +278,46 @@ in
};
};
# Shared by every hive's otel tier and its agents, so an agent's build
# carries the same values whichever hive renders it.
options.services.hyperhive.swarm.hiveOtel = {
collectorPort = lib.mkOption {
type = lib.types.port;
default = 4318;
description = ''
Port of every hive collector's OTLP/HTTP receiver, at that hive's
`services.hyperhive.network.bridgeIp`: the port agents dial at
`services.hyperhive.otel.collector.host`. 4318 is the OTLP/HTTP
default.
The port is contributed to
`services.hyperhive.network.exposeHostPorts`, which opens it on
the bridge interface only — so it is reachable from agent
containers and not from the outside world.
'';
};
extraResourceAttributes = lib.mkOption {
type = lib.types.str;
default = "";
example = "deployment.environment=prod";
description = ''
Extra comma-separated entries appended to
`OTEL_RESOURCE_ATTRIBUTES` after the built-in
`service.name` / `agent` / `hive` / `swarm` labels.
'';
};
};
config = lib.mkIf config.services.hyperhive.otel.enable (
let
otel = config.services.hyperhive.otel;
autheliaCfg = config.services.hyperhive.swarm.authelia;
deployCfg = config.services.hyperhive.deploy;
swarmOtelCfg = config.services.hyperhive.swarm.otel;
hiveOtelCfg = config.services.hyperhive.swarm.hiveOtel;
hiveName = config.services.hyperhive.hiveName;
listen = "${config.services.hyperhive.network.bridgeIp}:${toString otel.collector.port}";
listen = "${config.services.hyperhive.network.bridgeIp}:${toString hiveOtelCfg.collectorPort}";
swarmName = "otlphttp/swarm";
gatewayCfg = config.services.hyperhive.gateway;
authName = "oauth2client/swarm";
@ -351,7 +365,7 @@ in
{
# Reachable from agent containers and nowhere else: this opens
# the port on the bridge interface only.
services.hyperhive.network.exposeHostPorts = [ otel.collector.port ];
services.hyperhive.network.exposeHostPorts = [ hiveOtelCfg.collectorPort ];
# The name agents dial, answered with the bridge IP the receiver binds.
services.hyperhive.gateway.localNames = [ otel.collector.host ];

6
nix/host-modules/swarm-claude-login.nix
View file

@ -23,12 +23,12 @@ let
hyperhiveCfg = config.services.hyperhive;
# The `claude-code` the agents run, so this container does not trail them on
# the CLI; `fallback`, the container's own nixpkgs', only where the hive pins
# the CLI; `fallback`, the container's own nixpkgs', only where the swarm pins
# none.
claudeCode =
fallback:
if hyperhiveCfg.c0re.claudeCodePackage != null then
hyperhiveCfg.c0re.claudeCodePackage
if hyperhiveCfg.swarm.claudeCodePackage != null then
hyperhiveCfg.swarm.claudeCodePackage
else
fallback;
cfg = hyperhiveCfg.deploy.claude-login;

2
nix/host-modules/swarm-otel-service.nix
View file

@ -67,7 +67,7 @@ in
with it.
⚠️ **Deliberately not 4318**, the OTLP/HTTP default, because the
hive tier already uses it (`services.hyperhive.otel.collector.port`)
hive tier already uses it (`services.hyperhive.swarm.hiveOtel.collectorPort`)
and every swarm container shares the host's network namespace. Two
listeners claiming one port on one host is not a build failure —
it is a runtime coin toss over which one gets it, with nothing in

2
nix/host-modules/swarm-otel.nix
View file

@ -779,7 +779,7 @@ in
others = [
cfg.telemetryPort
cfg.producerPort
otelCfg.collector.port
config.services.hyperhive.swarm.hiveOtel.collectorPort
]
++ map (p: p.port) (lib.attrValues serviceProducers);
all = derived ++ others;

8
nix/host-modules/swarm-review-classifier.nix
View file

@ -24,12 +24,12 @@ let
hyperhiveCfg = config.services.hyperhive;
# The `claude-code` the agents run, so this container does not trail them on
# the CLI; `fallback`, the container's own nixpkgs', only where the hive pins
# the CLI; `fallback`, the container's own nixpkgs', only where the swarm pins
# none.
claudeCode =
fallback:
if hyperhiveCfg.c0re.claudeCodePackage != null then
hyperhiveCfg.c0re.claudeCodePackage
if hyperhiveCfg.swarm.claudeCodePackage != null then
hyperhiveCfg.swarm.claudeCodePackage
else
fallback;
cfg = hyperhiveCfg.deploy.review-classifier;
@ -100,7 +100,7 @@ let
otelEnv = lib.optionalAttrs otelCfg.enable {
CLAUDE_CODE_ENABLE_TELEMETRY = "1";
OTEL_METRICS_EXPORTER = "otlp";
OTEL_EXPORTER_OTLP_ENDPOINT = "http://${networkCfg.bridgeIp}:${toString otelCfg.collector.port}";
OTEL_EXPORTER_OTLP_ENDPOINT = "http://${networkCfg.bridgeIp}:${toString hyperhiveCfg.swarm.hiveOtel.collectorPort}";
OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf";
# Claude Code defaults to delta, which the metrics store drops.
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE = "cumulative";

19
nix/module-eval/swarm-services-switch.nix
View file

@ -99,11 +99,11 @@ let
deploy.builder.enable = false;
};
# Same, with the claude-code build the agents run pinned on the hive. Any
# Same, with the claude-code build the agents run pinned for the swarm. Any
# package serves: only the path the containers are pointed at is read.
swarmServicesPinnedClaude = hiveWithController {
deploy.allSwarmServices = true;
c0re.claudeCodePackage = pkgs.hello;
swarm.claudeCodePackage = pkgs.hello;
};
# Same, with one of those services placed on another host. Every derivation
@ -283,16 +283,25 @@ let
{
# The CLI is the one the agents run, not the container's own nixpkgs'.
# Unpinned is the control: it falls back to the container's own `claude-code`.
name = "the claude login minter and the review classifier run the claude-code the hive pins";
# serve.json is what hive-c0re renders every agent's `claudeCodePath` from.
name = "the agents, the claude login minter and the review classifier run the claude-code the swarm pins";
ok =
let
claudeOf =
host: container: unit: var:
host.containers.${container}.config.systemd.services.${unit}.environment.${var};
pinned = "${pkgs.hello}/bin/claude";
servedClaude =
host:
(builtins.fromJSON (
builtins.unsafeDiscardStringContext host.environment.etc."hyperhive/serve.json".text
)).claude_code_path;
in
claudeOf swarmServicesPinnedClaude "swarm-claude-login" "swarm-claude-login"
"SWARM_CLAUDE_LOGIN_CLAUDE" == pinned
servedClaude swarmServicesPinnedClaude == "${pkgs.hello}"
&& servedClaude swarmServicesHere == null
&&
claudeOf swarmServicesPinnedClaude "swarm-claude-login" "swarm-claude-login"
"SWARM_CLAUDE_LOGIN_CLAUDE" == pinned
&&
claudeOf swarmServicesPinnedClaude "swarm-review-classifier" "swarm-review-classifier"
"SWARM_REVIEW_CLASSIFIER_CLAUDE" == pinned