hyperhive — host options
services.hyperhive.c0re.package
hyperhive workspace package. Provides /bin/hive-c0re
(coordinator daemon) and /bin/hivectl (operator-facing host
CLI for ad-hoc administration + the host admin socket). Wired to
this flake’s packages.<system>.default by
nixosModules.default (via lib.mkDefault, so setting it here
wins).
Type: package
Default:
hyperhive.packages.${system}.default
Declared by:
services.hyperhive.c0re.adminUsers
Login users granted sudoless hivectl. Each is added to the
hive-admin group, which group-owns the host admin socket
(/run/hyperhive/host.sock, mode 0660) — so listed users drive
hivectl (and thus the whole hive) without sudo.
This is a real privilege grant: the admin socket is full hive
control — spawn / kill / destroy / deploy — see docs/trust-boundary/boundary.md.
Keep the list to trusted operators. Empty (the default) keeps the
socket root-only, as before.
Type: list of string
Default:
[ ]
Example:
[
"alice"
]
Declared by:
services.hyperhive.c0re.agentBaseToplevel
Pre-built agent-base container system closure, pulled into the
host system closure when preBuildAgentTemplates is on. Wired
by nixosModules.default; only evaluated when that option is
enabled.
Type: package
Default:
hyperhive.packages.x86_64-linux.agent-base-toplevel
Declared by:
services.hyperhive.c0re.agentCpuQuota
systemd CPUQuota= applied to every agent container via a
container@h-<name>.service.d/ drop-in written on each
spawn/rebuild. Expressed as a percentage of one CPU core —
"200%" allows each agent to use up to 2 cores. Bump this if
agents are hitting CPU limits during builds or heavy tool use.
For a hive-wide cap across all containers, set
systemd.slices.machine.serviceConfig.CPUQuota in your NixOS
config (all nspawn containers live in machine.slice).
Type: string
Default:
"200%"
Example:
"400%"
Declared by:
services.hyperhive.c0re.agentCpuWeight
systemd CPUWeight= applied to every agent container via the
same drop-in as agentCpuQuota. This is the cgroup v2
cpu.weight relative share, not a cap: a low-weight
container still gets the whole machine when nothing else wants
it, and the weight only decides who yields under contention.
That makes it the complement of agentCpuQuota, which throttles
even on an idle host.
The kernel default is 100. The hyperhive default of 80 means
agent containers yield slightly to everything that is not on
this drop-in path — host services and the infrastructure
containers (hive-forge, hive-gateway, hive-matrix), which
stay at 100. Note this is a hive-wide
value, so it does not rank agents against each other: they all
share one weight.
Set to null to leave CPUWeight= out of the drop-in entirely —
the container then inherits the kernel default and the generated
unit file is identical to one from before this option existed.
Type: null or integer between 1 and 10000 (both inclusive)
Default:
80
Example:
null
Declared by:
services.hyperhive.c0re.agentIoWeight
systemd IOWeight= applied to every agent container via the
same drop-in as agentCpuQuota — the block-IO counterpart of
agentCpuWeight, with the same relative-share, contention-only
semantics.
Caveat: IOWeight= maps to the cgroup v2 io.weight knob, which
is only honoured when the io.cost (blk-iocost) controller is
enabled for the backing device, or when the device uses the BFQ
scheduler. On a host running none/mq-deadline/kyber without
iocost QoS configured, systemd writes the value and the kernel
ignores it — harmless, but it will measure as a no-op. Check with
cat /sys/fs/cgroup/io.cost.qos on the host, and set this to
null to omit the setting rather than write one nothing reads.
Type: null or integer between 1 and 10000 (both inclusive)
Default:
80
Example:
null
Declared by:
services.hyperhive.c0re.agentMemoryMax
systemd MemoryMax= applied to every agent container via the
same drop-in as agentCpuQuota.
Type: string
Default:
"4G"
Example:
"8G"
Declared by:
services.hyperhive.c0re.assets
Bundled static runtime assets (see nix/packages/assets.nix): the
project’s branding family + the claude system-prompt template +
claude-settings JSON. Output has share/hyperhive/{branding,prompts}/;
passed to hive-c0re’s systemd unit via HIVE_ASSETS_DIR
(hive_sh4re::assets::* resolve paths underneath). Override to
ship customised branding or prompts without rebuilding the
rust derivation.
Type: package
Default:
hyperhive.packages.${system}.assets
Declared by:
services.hyperhive.c0re.buildSlots
Number of nix-heavy job-queue nodes (container prebuilds, profile swaps, first-spawn creates, meta lock bumps) hive-c0re runs concurrently. The default of 1 serializes all heavy nix work; raise it on hosts with the cores/RAM to build several agent toplevels at once. Per-agent correctness is independent of this count — each agent’s container-affecting operations are serialized by its lifecycle lease regardless.
Type: positive integer, meaning >0
Default:
1
Example:
2
Declared by:
services.hyperhive.c0re.frontend
Bundled frontend dist (see nix/packages/frontend.nix). Output
has dashboard/ and agent/ subdirectories — hive-c0re serves
dashboard/ via tower_http::ServeDir from the path passed
in HIVE_STATIC_DIR. Override to ship a custom dashboard SPA;
the JSON contract (/api/state, the SSE streams, the action
endpoints) is the source of truth for any replacement.
Type: package
Default:
hyperhive.packages.${system}.frontend
Declared by:
services.hyperhive.c0re.hyperhiveFlake
Store path of the hyperhive flake source (no fragment). hive-c0re
reads it to tell which revision is running, and the swarm builder
builds on it. The meta flake does not use it: that pins
hyperhive by forge URL and hyperhiveRev. Wired by
nixosModules.default to this flake’s own filtered source.
Type: string
Default: the hyperhive flake’s own filtered source store path
Declared by:
services.hyperhive.c0re.hyperhiveRev
Git rev of the hyperhive checkout this host runs. hive-c0re pins
the generated meta flake’s hyperhive input to
git+<forge>/hyperhive/hyperhive.git?rev=<rev>, and nixpkgs
follows that input. Wired by nixosModules.default from
self.rev, which a dirty tree does not have; with null,
hive-c0re refuses to render the meta flake.
Type: null or string
Default:
the hyperhive flake’s own self.rev
Declared by:
services.hyperhive.c0re.modelPrices
Per-model USD prices (per million tokens) used for the
hive-wide cost estimate on the dashboard’s ST4TS tab. Each key
is a model-family short name matched case-insensitively as a
substring of the active model id at runtime (e.g. "sonnet"
matches "claude-sonnet-4-5"); the longest matching key wins, so
a specific entry beats a generic family name. Any model not
covered by this table falls back to hive-c0re’s built-in
estimate.
The defaults track Anthropic list pricing at the time of
writing — override them here to keep the estimate current
without a code change. Passed to hive-c0re serve as JSON via
--model-prices; read only by hive-c0re itself (not injected
into containers). Changes apply on the next host rebuild.
Type: attribute set of (submodule)
Default:
{
haiku = {
cache_read = 0.1;
cache_write = 2.0;
input = 1.0;
output = 5.0;
};
opus = {
cache_read = 0.5;
cache_write = 10.0;
input = 5.0;
output = 25.0;
};
sonnet = {
cache_read = 0.3;
cache_write = 6.0;
input = 3.0;
output = 15.0;
};
}
Example:
{
sonnet = {
cache_read = 0.3;
cache_write = 6.0;
input = 3.0;
output = 15.0;
};
}
Declared by:
services.hyperhive.c0re.modelPrices.<name>.cache_read
USD per million cache-read tokens.
Type: nonnegative integer or floating point number, meaning >=0
Declared by:
services.hyperhive.c0re.modelPrices.<name>.cache_write
USD per million cache-creation (write) tokens.
Type: nonnegative integer or floating point number, meaning >=0
Declared by:
services.hyperhive.c0re.modelPrices.<name>.input
USD per million input tokens.
Type: nonnegative integer or floating point number, meaning >=0
Declared by:
services.hyperhive.c0re.modelPrices.<name>.output
USD per million output tokens.
Type: nonnegative integer or floating point number, meaning >=0
Declared by:
services.hyperhive.c0re.nixpkgsFlake
Store-path URL of the nixpkgs the swarm builder’s check flake
builds on. The generated meta flake does not use it: its nixpkgs
follows hyperhive/nixpkgs.
Defaults to "path:${pkgs.path}", the nixpkgs the host NixOS
module was evaluated with.
Type: string
Default:
"path:${pkgs.path}"
Declared by:
services.hyperhive.c0re.preBuildAgentTemplates
Pre-fetch the agent-base container system closure, which every agent builds from, into the host’s /nix/store as part of this host’s NixOS build, instead of letting the first agent spawn do all the work.
Enabling this adds roughly the full nixpkgs runtime closure +
claude-code + the harness binary to your system closure size
(low single-digit GB), but the first nixos-container start
for any agent then completes in seconds instead of minutes
because nothing’s left to fetch.
Off by default because the toplevel is pinned to
x86_64-linux (nixos-containers run native arch). Enabling
on an aarch64 host would force nix to build the x86 closure
via cross or a remote builder, which is rarely what you want.
Flip to true on an x86_64 host when you care more about
first-spawn latency than host store size — or just
nix build .#agent-base-toplevel once manually to warm the
store.
Type: boolean
Default:
false
Example:
true
Declared by:
services.hyperhive.c0re.xdgIcons
XDG icon set + .desktop entries for hyperhive processes (see
nix/packages/hive-xdg-icons.nix), installed into the host
system packages so desktop environments can match hyperhive
processes to their icon.
Type: package
Default:
hyperhive.packages.${system}.xdg-icons
Declared by:
services.hyperhive.domain
Canonical host domain for hyperhive subsystems that need a
stable name (currently: services.hyperhive.swarm.matrix.serverName
derives from this, defaulting to
matrix.${services.hyperhive.domain} when serverName is
null). Required when
services.hyperhive.deploy.hive-controller.enable — eval fails
with a helpful message if it’s unset (it’s baked into matrix on
first boot and drives the gateway/forge/agent URLs, with no safe
default; changing it later is destructive). Exposed to agents as
HYPERHIVE_HIVE_DOMAIN; consumed by
hive-agent::identity::hive_domain() for <name>@<domain>
qualified labels.
Deprecated as a place to write. It is read from this hive’s
own entry in services.hyperhive.swarm.hives, whose domain
defaults to <hiveName>.<swarm.domain> — so a conventional hive
states nothing at all, and a non-conventional one states its
address in the directory every other hive reads. Setting it here
still wins and still works, with a warning: the directory is
shared, this option is not, so a value written only here is
invisible to the rest of the swarm.
Type: null or string
Default:
services.hyperhive.swarm.hives.${hiveName}.domain, or null when there is no entry for this hive
Example:
"darkest.space"
Declared by:
services.hyperhive.gateway.enable
Run the hive’s reverse proxy (nginx) on this host.
Type: boolean
Default:
false
Declared by:
services.hyperhive.gateway.dns.enable
Run the hive’s resolver (dnsmasq) on this host.
Type: boolean
Default:
false
Declared by:
services.hyperhive.gateway.hsts.enable
Add Strict-Transport-Security to all gateway vhosts.
Disabled by default: HSTS pins HTTPS in the browser’s HSTS preload list; enabling it on a deployment that later loses TLS will lock browsers out until the max-age expires. Only enable this when you are certain TLS is permanent.
The gateway always terminates TLS (self-signed floor), so HSTS is always served over https when enabled — but mind the warning above: HSTS pins https in the browser, so only enable it when TLS is permanent for this deployment.
Type: boolean
Default:
false
Declared by:
services.hyperhive.gateway.hsts.includeSubDomains
Whether to include includeSubDomains in the HSTS header.
Only disable this if the gateway host has sub-domains that
intentionally serve plain HTTP.
Type: boolean
Default:
true
Declared by:
services.hyperhive.gateway.hsts.maxAge
Value for the max-age directive in seconds.
Default: 31536000 (1 year), which is the value required for
HSTS preload list submission. Use a shorter value (e.g. 86400)
while testing so browsers forget the pin quickly.
Type: positive integer, meaning >0
Default:
31536000
Example:
86400
Declared by:
services.hyperhive.gateway.httpsPort
TCP port for the TLS-terminated vhosts. Default 443. The gateway
always terminates TLS (self-signed is the implicit floor when no
tls.certDir / ACME is configured), so this port is always active
alongside the plain-http port.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
443
Example:
8443
Declared by:
services.hyperhive.gateway.localHostsEntry
Add an /etc/hosts entry mapping services.hyperhive.domain
to 127.0.0.1 on the host. Useful for local deployments +
tests where there’s no real DNS for services.hyperhive.domain
but the operator (or browser-based tests) want to hit
http://${services.hyperhive.domain} to exercise the
gateway shape. Off by default — operators running with real
DNS shouldn’t have a stale /etc/hosts entry sticking
around. Requires services.hyperhive.domain to be set.
services.hyperhive.deploy.singleHostSwarm turns this on as
part of saying “this box is the whole deployment”: that mode
means there is no real DNS for these names and the operator is
browsing them from the host itself. Set it here explicitly to
override in either direction.
Type: boolean
Default:
false
Example:
true
Declared by:
services.hyperhive.gateway.openFirewall
Open port in the host firewall. Off by default (secure-by-default).
Flip to true to expose the gateway to
the operator’s browser / external clients — required for any
out-of-host reach, since the agents themselves talk to
hive-c0re via the per-agent unix sockets and don’t need the
nginx vhost. Leave off when running behind another reverse
proxy (e.g. caddy / traefik on the host) that handles TLS
termination + forwards to port.
Type: boolean
Default:
false
Example:
true
Declared by:
services.hyperhive.gateway.port
TCP port the gateway listens on. Default 80 (canonical web port). nginx runs on the host as root, so it can bind <1024; if 80 is already taken on the host (existing nginx, traefik, etc.) override to an unused port like 8080 or move the conflicting service.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
80
Example:
8080
Declared by:
services.hyperhive.gateway.statusPort
Loopback TCP port nginx serves its stub_status counters on, at
http://127.0.0.1:${statusPort}/stub_status. The hive’s collector
(every hive runs one) reads it with its nginx
receiver.
TCP rather than a unix socket because that receiver can only dial
http://. Anything on the host can read these counters; they are
connection and request totals, nothing per-client.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
8085
Declared by:
services.hyperhive.gateway.swaggerUiTheme
Full Swagger UI static dist, hyperhive-themed (see
nix/packages/swagger-ui-theme.nix, built on
nix/packages/swagger-ui-dist.nix). The gateway serves this
whole tree directly at /api/docs/ — hive-c0re hosts none of
it, only the dynamic /api/openapi.json route (proxied
through, unaffected by this option). Override to ship a
custom theme (or the plain vendored dist) without a gateway
rebuild.
Type: package
Default:
hyperhive.packages.${system}.swagger-ui-theme
Declared by:
services.hyperhive.gateway.tls.acme.enable
Let the gateway’s nginx obtain and renew TLS certificates
automatically via ACME (Let’s Encrypt). When enabled, each
vhost calls out to Let’s Encrypt using the HTTP-01
challenge on port (default 80) and stores certs in the
gateway’s persistent state dir on the host.
Requirements:
services.hyperhive.domainmust be set and publicly DNS-resolvable to this host.services.hyperhive.gateway.openFirewall = trueso Let’s Encrypt can reach/.well-known/acme-challenge/.tls.acme.emailmust be set (ACME account contact).
Mutual exclusion: tls.certDir set together with
tls.acme.enable = true fails at eval — pick one TLS source.
Typical setup:
services.hyperhive.gateway = {
openFirewall = true;
tls.acme = {
enable = true;
email = "admin@example.com";
};
};
Type: boolean
Default:
false
Example:
true
Declared by:
services.hyperhive.gateway.tls.acme.email
Email address for the ACME account registration with
Let’s Encrypt. Required when tls.acme.enable = true.
Let’s Encrypt sends expiry warnings to this address.
Type: null or string
Default:
null
Example:
"admin@example.com"
Declared by:
services.hyperhive.gateway.tls.certDir
Path to a host directory containing a TLS certificate and
private key for nginx. When set, nginx listens on httpsPort
and uses this cert, overriding the self-signed default — the
store-issued self-signed leaf is skipped entirely.
nginx reads <certDir>/<tls.certName> and
<certDir>/<tls.keyName> directly — it runs on the host, so
the directory needs no bind mount and no copy.
Default filenames (cert.pem / key.pem) match the output
layout of nixpkgs’s security.acme module.
Typical ACME setup:
security.acme.certs."example.com" = { ... };
services.hyperhive.gateway.tls.certDir =
config.security.acme.certs."example.com".directory;
Mutual exclusion with tls.acme.enable — set one or the other,
not both.
Type: null or absolute path
Default:
null
Example:
"/var/lib/acme/example.com"
Declared by:
services.hyperhive.gateway.tls.certName
Filename of the TLS certificate within tls.certDir. Defaults
to cert.pem which matches nixpkgs’s security.acme output.
Type: string
Default:
"cert.pem"
Declared by:
services.hyperhive.gateway.tls.keyName
Filename of the TLS private key within tls.certDir. Defaults
to key.pem which matches nixpkgs’s security.acme output.
Type: string
Default:
"key.pem"
Declared by:
services.hyperhive.gateway.upstreamHost
Host the gateway proxies non-static requests to. Defaults to
127.0.0.1 because nginx runs on the host itself, so loopback
resolves directly to hive-c0re.
Type: string
Default:
"127.0.0.1"
Declared by:
services.hyperhive.gateway.upstreamPort
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.deploy.hive-controller.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.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
7000
Declared by:
services.hyperhive.gateway.vhosts.<name>.certificate
A certificate pair to serve instead of the one the gateway
picks for this name (gateway.lib.tlsFor). For a name whose
certificate is issued outside the gateway’s own leaves.
Type: null or (submodule)
Default:
null
Declared by:
services.hyperhive.gateway.vhosts.<name>.certificate.cert
Path of the certificate nginx serves for this name.
Type: string
Declared by:
services.hyperhive.gateway.vhosts.<name>.certificate.key
Path of the private key for cert. A path, never a value.
Type: string
Declared by:
services.hyperhive.gateway.vhosts.<name>.securityHeaders
Whether the gateway puts its security headers ahead of this
vhost’s extraConfig. Off only for a vhost that answers no
request with a response, such as the catch-all.
Type: boolean
Default:
true
Declared by:
services.hyperhive.hiveName
Human-readable name of this single-host hive instance.
Required when this host runs a hive, the swarm’s secret store
or its homeserver
(services.hyperhive.deploy.hive-controller.enable,
deploy.bao.enable, deploy.matrix.enable). Distinct from
services.hyperhive.domain (the machine-addressable DNS name)
and not merely cosmetic: a hive occupies
<hiveName>.<swarm.domain>, so this is the label the hive is
addressed by as well as the one it is called. Exposed to
agents as HYPERHIVE_HIVE_NAME; surfaced in the dashboard
chrome and per-agent system prompt.
Type: null or string
Default:
null
Example:
"pr1ma"
Declared by:
services.hyperhive.network.enable
Bring up the hive bridge, its NAT and its firewall rules on this host.
Type: boolean
Default:
false
Declared by:
services.hyperhive.network.bridgeIp
IPv4 address assigned to the bridge interface on the host
side. Agents use this address as their DNS server (the hive’s
dnsmasq binds here). Default 10.42.0.1
is in RFC 1918 space and unlikely to clash with operator’s
existing setup; override if a different range is already in
use.
Type: string
Default:
"10.42.0.1"
Example:
"172.30.0.1"
Declared by:
services.hyperhive.network.bridgeName
Name of the host-side bridge interface the hive uses for
inter-container traffic. Kept short so it survives the
IFNAMSIZ (15-char) cap, and prefixed so it’s obviously
hive-managed in ip link output.
Type: string
Default:
"hive-br0"
Example:
"h0"
Declared by:
services.hyperhive.network.bridgePrefixLength
Netmask prefix length for the bridge subnet. Default /24
gives 254 usable per-agent addresses, enough for any
single-host hive. Operator with a larger swarm or a tighter
addressing scheme overrides.
Type: signed integer
Default:
24
Example:
16
Declared by:
services.hyperhive.network.exposeHostPorts
TCP ports on the host that agent containers may reach at the bridge
IP (bridgeIp). Each listed port P is opened on the bridge-interface
firewall, so an agent can connect to ${bridgeIp}:P (default
10.42.0.1:P).
Use this to let agents reach a host-local service you run yourself —
a database, a scratch HTTP endpoint, anything listening on
${bridgeIp}:P.
The host service must bind an address reachable from the bridge —
0.0.0.0 or the bridge IP (bridgeIp) — not loopback-only. The
bridge→127.0.0.0/8 DROP rule (defence-in-depth) is unchanged: this
only opens the firewall, it does not bridge loopback. A service that
binds 127.0.0.1 only is still unreachable; rebind it to 0.0.0.0.
The exposed port is reachable by EVERY agent on the bridge subnet (same as DNS/gateway), so only expose services safe for any agent to reach.
Type: list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
[ ]
Example:
[
5432
]
Declared by:
services.hyperhive.otel.clientSecretFile
Absolute path to this hive’s OAuth2 client secret, used to authenticate to the swarm’s collector as this hive.
Whether this is set is what decides whether this tier authenticates at all. A credential is the only thing that makes authenticated egress possible, so its presence is the condition rather than a second switch that could disagree with it.
Defaults, on a host holding the hive’s store identity
(services.hyperhive.deploy.bao.clientCertFile), to the file
swarm-bao-hive-otel-oidc.service fetches from the swarm secret
store under that identity. Set it to deliver the secret some other
way; that unit then does not exist.
Read by LoadCredential, so it is never evaluated by nix, never
copied into the store and never passed in argv.
Type: null or string
Default:
"/var/lib/hive-otel-oidc/${swarm.authelia.hiveClientPrefix}${hiveName}.secret" when deploy.bao.clientCertFile and clientKeyFile are set, else null
Example:
"/var/lib/secrets/hive-telemetry.secret"
Declared by:
services.hyperhive.otel.collector.enable
Whether this host runs the hive tier’s collector. Not a switch:
every host that runs a hive
(services.hyperhive.deploy.hive-controller.enable) runs
one, and so does a host carrying all the swarm’s shared services
(services.hyperhive.deploy.allSwarmServices), whose own
containers export to it.
Agents export to it unauthenticated at
services.hyperhive.otel.collector.host, a name this
hive’s resolver answers with a bridge address only its own
containers can reach. It forwards to the swarm’s collector
(services.hyperhive.deploy.swarm-otel.enable), which holds
the upstream credential and writes the swarm’s store, so neither an
agent nor this tier ever sees the credential.
⚠️ The collector is in the path of all telemetry. It runs on the same host as the agents and restarts on failure; telemetry is not the control plane, so degraded telemetry is not degraded operation, but the export does not survive independently of anything host-side.
Type: boolean (read only)
Default:
deploy.hive-controller.enable || deploy.allSwarmServices
Declared by:
services.hyperhive.otel.collector.host
The name agents reach this hive’s collector on. A literal, the same
on every hive and in every swarm: each hive’s own resolver answers
it with its own bridge IP, so an agent’s build carries neither a
swarm domain nor a hive-specific address. The agent module’s
services.hyperhive.agent.otel.endpoint default spells the same
name.
It sits outside every domain a hive or the swarm serves: a hive’s
domain is <hiveName>.<swarm.domain>, so it never ends in .hive.
Type: string (read only)
Default:
"hive-collector.hive"
Declared by:
services.hyperhive.otel.scrapeTargets
Prometheus exposition endpoints this hive’s collector scrapes, as
<job name> = "<host>:<port>".
A service declares its own entry, from its own module, under its
own enable — the same rule as the swarm tier’s option of the
same name, and for the same reason: an entry exists only where the
service that named it runs, so the scraper and its target are
co-located by construction rather than by luck.
⚠️ This tier, not the swarm one, is where a HIVE-owned target
belongs. The two are not interchangeable: a swarm service does
not belong to a hive, so its samples must never acquire a hive
label — which is why that scraper lives one tier up. Putting a
hive-owned target there would either mislabel it or leave it
unattributed.
Scraping is unauthenticated on purpose. This receiver is a prometheus-to-OTLP converter sitting next to what it reads, in the same trust position as the agents already pushing to this collector; the authenticated hop is the collector’s own export onward, which is one hop for the whole hive rather than one per target.
Not empty on a default hive: this collector’s own endpoint
is always in here, so the scrape receiver is emitted everywhere.
The != { } guards around it stay meaningful — the set can still
be forced empty, and a prometheus receiver with nothing to
scrape is a config that renders, starts and collects nothing.
Type: attribute set of string
Default:
{ }
Example:
{ hive-forge = "127.0.0.1:3000"; }
Declared by:
services.hyperhive.otel.telemetryPort
Port this collector serves its own metrics on — queue depth, refused and dropped samples, exporter failures. How you find out that telemetry is being lost.
8888 is the collector’s built-in default; declaring it here makes
the value configured rather than implied, which is the point of
the option. An undeclared port is invisible to anything comparing
ports, so a second collector on the same host picking the same
number fails at bind() rather than at eval —
services.hyperhive.swarm.otel.telemetryPort sidesteps 8888 by
hand for that reason.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
8888
Declared by:
services.hyperhive.snapshotStore.enable
Run the swarm snapshot store on this host: a btrfs receive
endpoint that hives push agent snapshots to over the WireGuard
mesh. Off by default — it is a distinct deployment role, not
part of a hive.
Requires services.hyperhive.deploy.wireguard.enable: the mesh
is both the transport and the authentication, so there is no
meaningful configuration without it.
Type: boolean
Default:
false
Declared by:
services.hyperhive.snapshotStore.path
Root of the snapshot tree. Must be on a btrfs filesystem —
btrfs receive fails otherwise. One subvolume directory per
agent is created beneath it, so an agent’s incremental chain
stays contiguous across a migration between hives.
Type: absolute path
Default:
"/var/lib/hyperhive-snapshots"
Declared by:
services.hyperhive.snapshotStore.port
TCP port the receiver listens on. Bound to this host’s WireGuard mesh address only — never a wildcard — so it is reachable exactly by mesh peers and by nothing else.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
51821
Declared by: