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

docs: reflect the new nix layout and removed options

Browse source
This commit is contained in:
müde 2026-07-13 22:23:20 +02:00
commit eba3f206ab
4 changed files with 16 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -154,7 +154,7 @@ account), it prints the token to stdout and writes nothing.
nix develop -c cargo check
nix flake check # rust + nix + toml fmt + clippy
# deploy from a host config that imports hyperhive.nixosModules.hive-c0re
# deploy from a host config that imports hyperhive.nixosModules.default
nix flake update --update-input hyperhive
sudo nixos-rebuild switch --flake .#<host>
```

3
docs/gateway.md
View file

@ -89,8 +89,7 @@ now set unconditionally for every agent. The mechanism:
1. **Agent side**. `HIVE_WEB_SOCKET=/run/hive-agent/<name>/web.sock`
is set on every harness service env; `web_ui::serve` binds a
`UnixListener` at that path. The deprecated
`hyperhive.web.useUnixSocket` option is now a no-op.
`UnixListener` at that path.
2. **Host side**. `hive-c0re` bind-mounts the per-agent subdir
(`/run/hive-agent/<name>/`) into the agent's container. Dir
bind, not file bind — file bind-mounts don't survive the

18
docs/gotchas.md
View file

@ -232,7 +232,7 @@ CI on drift).
## Split asset derivations away from the rust workspace
`nix/assets.nix` builds the branding SVG/PNG family + claude
`nix/packages/assets.nix` builds the branding SVG/PNG family + claude
system-prompt template + claude-settings JSON as its own derivation,
separate from the hive-ag3nt / hive-c0re crates. Reason: when the
rust build's `src` was the whole repo tree, any tweak to
@ -246,7 +246,7 @@ derivation's `nativeBuildInputs`.
## Weston VNC compositor (per-agent `hyperhive.gui.enable`)
`nix/templates/weston-vnc.nix` adds an optional Weston Wayland
`nix/agent-modules/weston-vnc.nix` adds an optional Weston Wayland
compositor with the VNC backend, surfaced as
`hyperhive.gui.enable = true` per-agent. The harness's
`/screen/ws` WebSocket relay (`docs/web-ui/agent.md::Per-agent endpoints`)
@ -323,7 +323,7 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
## Nix options reference (`nix/docs/default.nix`)
`pkgs.nixosOptionsDoc` over two evaluated module trees:
`hostEval` (a stub NixOS system loading `hive-c0re.nix` with every
`hostEval` (a stub NixOS system loading the `nix/host-modules/` aggregator with every
hyperhive subsystem `mkForce false` so heavy build inputs stay out of
the eval) and `agentEval` (evaluates `agent.nix` fresh for the
per-agent options tree).
@ -356,7 +356,7 @@ options tree picks up everything under that root — picking against
stray roots produces an empty tree and renders the host page as
template chrome with no `<h2>` headers.
### Docs drv stability: `nixSrc` + stub overlay
### Docs drv stability: `nixSrc`
Naively, the docs evaluation depends on `self` (the flake's store path),
so every commit — even Rust-only or frontend-only changes — produces new
@ -371,11 +371,11 @@ The fix (`nix/docs/default.nix`):
context. The resulting store path is content-addressed from the nix/
file contents only. Docs drvs only change when a `.nix` file changes.
2. **`docsStubOverlay`** — replaces `self.overlays.default` with stub
packages (`pkgs.emptyFile` / `pkgs.emptyDirectory`) for the docs eval.
`nixosOptionsDoc` renders `defaultText` for all package options anyway;
the stubs prevent attribute-missing eval errors without pulling in the
Rust or frontend build closure.
2. The package options the modules consume (`hyperhive.packages.*`,
`services.hyperhive.c0re.*`) carry no in-module defaults and every
default that references them has a `defaultText`, so the doc walk
never forces a package — no stubs needed, and the Rust/frontend
build closure stays out of the eval.
3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
(not `self`), so the docs drv dependency chain ends at `nixSrc`.

10
docs/network.md
View file

@ -4,11 +4,11 @@ Host-side bridge + per-agent private-netns isolation — always on
whenever hyperhive is enabled. Configured via
`services.hyperhive.network.*`.
> **Historical note:** the bridge and private-netns isolation landed in
> two separate phases. `services.hyperhive.network.enable` and
> `services.hyperhive.network.isolateContainers` are retained as
> deprecated no-op options so existing configs eval without change; both
> are ignored — isolation is the only mode.
> Isolation is the only mode — there is no shared-netns fallback. The
> former `services.hyperhive.network.enable`,
> `services.hyperhive.network.isolateContainers` and
> `services.hyperhive.network.upstreamDns` options were removed; a
> config that still sets one fails eval with a removal message.
## Container shape (where dnsmasq lives)