Backfills the agent /stats page docs after the P1 stats enrichments:
the result-trend stacked bar (per-bucket result outcomes over time) and
the cache hit-rate + tokens/turn summary chips.
C0NT41N3R L04D on the SYST3M tab + GET /api/container-resources.
Backend (hive-c0re/src/container_stats.rs): reads cgroup v2 cpu.stat +
memory.{current,peak,max} for each running agent machine
(machine-h\x2d<name>.scope under machine.slice), read-only/world-
readable so no hive-priv. CPU is a two-sample (~200ms) host-normalised
percentage; one shared sleep covers all agents. Skips agents whose
scope dir is absent (= not running). Network omitted: agents share the
host netns, no per-container counter.
Frontend: a polled C0NT41N3R L04D table on SYST3M (agent / cpu / mem /
peak / limit with meter bars), reusing the ST4TS table style. Polls
/api/container-resources every 5s only while the tab is active.
Backend reviewed-in-principle by damocles (path escaping + cpu delta
math); ping for the on-host sign-off.
Adds the ST4TS tab to the strip list + a section covering the swarm
rollup, the /api/stats-hive endpoint shape, the read-only/skip-missing
aggregation, pull-on-activation, and the labelled cost estimate. Ships
with the feature (this branch / PR).
Replaces the fork-and-PR instructions with the supported no-fork path
now that the CLI helper shipped: hive-forge clone + pr-create --agit.
Agents are read-only collaborators, so they push HEAD to
refs/for/<base>/<topic> via AGit instead of forking. Same --topic
updates the open PR.
Per #1407 review: the options reference should be markdown here; the
HTML + CSS belongs in the website repo where the theme lives and the
stylesheet can be shared with /docs.
- nix/docs/default.nix: drop the cmark-gfm HTML rendering, the inline
<style>, and the HTML index. Emit index.md + host.md + agent.md only
(CommonMark from nixosOptionsDoc).
- Remove nix/docs/style.css.
- Update docs/gotchas.md + CLAUDE.md to describe the md-only output and
point at the website for HTML rendering.
The website (hyperhive/website#26) renders these .md to themed HTML for
/options/, sharing one docs.css with the prose /docs/ tree.
The CSS theme-variable reference documents the dashboard/agent web-UI
stylesheets, so it belongs under docs/web-ui/ alongside shape/dashboard/
agent. Wire it into the web-ui.md index (split list + reading path) and
the CLAUDE.md file map. Closes#1405.
The "hive-forge container shape" section described the container
isolation model but omitted the port and firewall knobs that operators
need when exposing forge externally or overriding the Forgejo ROOT_URL.
Add two subsections:
"Network and port configuration" — covers httpPort (default 3000),
sshPort (default 2222), and openFirewall (default false, was previously
true — breaking change note included). Explains the shared-netns
rationale for why openFirewall is safe to leave off for agent use but
must be set for browser/external-git-client access. Clarifies that
forge.behindGateway obviates forge.openFirewall for HTTP reach.
"rootUrl override" — documents forge.rootUrl (default null) with the
auto-derivation table (behindGateway ? http://domain/ : http://domain:port/)
and explains when to override (TLS, https:// clone URLs, bespoke shapes).
Notes the auto-derivation always produces http://, so TLS operators must
set rootUrl explicitly.
The sentence 'ruth is always reachable regardless of the list' documents
a bug in check_send_allowed (name-based carve-out), not intended
behavior. The structural parent carve-out is fine to mention since it's
topology-based, not name-based.
Updated example to show [ "operator" ] (restrict to operator-only)
and replaced the ruth-name claim with a note about the parent carve-out.
Five per-agent agent.nix options were undocumented:
- hyperhive.allowedRecipients — restricts which peers send() accepts;
note added inline to the send tool description
- hyperhive.claudeMarketplaces — Claude Code plugin marketplace sources
(default: official Anthropic marketplace)
- hyperhive.claudePlugins — plugin specs installed at harness boot
- hyperhive.claudePluginsAutoUpdate — pull latest marketplace index
before install; off by default
- hyperhive.cargo.shortMessages — shell wrapper injecting
--message-format short on cargo compile subcommands; on by default
The daemon does not call join_room_by_id. It fires a wake and writes
to mcp-loose-ends/matrix.json; the agent calls list_invites + join_room.
Replace the inaccurate 'Auto-accept invites' paragraph with 'Invite
wakes' describing the actual flow. Merge the pending-invites paragraph
into a single accurate block.
The matrix.md provisioning section mentioned trustedServers in passing
("wired up later by extending trustedServers") but never explained it
as a configurable option, and maxRequestSize was undocumented entirely.
Add a "Configuration tuning" subsection before "Assertion rationale":
- trustedServers (default []) — list of peer homeserver names to trust;
federation is protocol-on but no peer trusted until listed; link to
swarm.md for the multi-hive use case.
- maxRequestSize (default 20 MB) — request body limit matching the
matrix-spec recommendation; when and why to raise or lower it.
SVG path for per-agent visual identity — used in the page header,
favicon, Forgejo profile avatar (forge-avatar-sync), and Matrix
profile avatar (matrix-avatar-sync).
The compaction section already documented HIVE_COMPACT_WATERMARK_TOKENS
but didn't mention the per-agent nix option (hyperhive.autoCompact,
default true) that maps to it.
Add a short note after the watermark paragraph explaining that operators
can set autoCompact = false in agent.nix to disable proactive compaction,
and note the reactive path still applies. Useful for sonnet/opus agents
where the 75% heuristic fires before the session is actually full.
Three host-level NixOS options in services.hyperhive.c0re were
undocumented. Add a new 'Host-level resource + performance options'
section to coordinator.md covering:
- agentCpuQuota (default 200%) — CPUQuota= drop-in per container
- agentMemoryMax (default 4G) — MemoryMax= drop-in per container
- preBuildAgentTemplates (default false) — pre-fetch agent closures
into host nix store; trade system closure size for first-spawn speed;
warn against enabling on aarch64 hosts
GET /api/tool-groups and GET /api/capabilities both return a
descriptions map (name → short string) added in feat(#1082). The
map drives native browser tooltips on column headers in the
P3RM1SS10NS tab. The API docs still showed the old 2-field shape.
The matrix wake body description said '[matrix] <sender> in <room>:
<first-100c>...' (old single-line teaser). After feat(#1137) it's now
a richer format:
- Single room, 1 message: terse one-liner with sender + body
- Single room, N messages: count + room name
- Multi-room: bulleted list with per-room summaries
Also note that the same breakdown appears in get_loose_ends via the
UnreadMatrix entry.
The internal/knowledge forge repo and its /knowledge container bind-mount
have been live since feat(#1167) but had no docs/ entry — only a mention
in the agent system prompt.
Add docs/knowledge.md covering:
- Agent access (/knowledge read-only bind-mount inside every container)
- Repository layout (internal/knowledge, auto-seeded README)
- Sync mechanism (webhook on push + periodic pull fallback)
- State paths (/var/lib/hyperhive/knowledge on host)
- Contribution workflow (fork + PR, no direct push)
Also add a file-map entry and reading-path bullet in CLAUDE.md.
hivectl has verbs scattered across CLAUDE.md and domain docs (gateway.md
has the gateway subcommands, matrix.md has a brief mention) but no
single cheatsheet. Add docs/tools/hivectl.md covering all subcommands:
- forge create-user: provision/refresh agent or human forge accounts
- matrix create-user / sync-admin / promote-user / reset-password
- gateway create-user / delete-user / list-users (htpasswd management)
- agents restart / restart-all (container lifecycle via admin socket)
- choom <name> [--fresh]: interactive claude session in agent container
Also add a reading-path entry to CLAUDE.md pointing at the new file.
persistence.md: bash-tasks/ says "persist until container purge" but
bash_tasks_vacuum now runs hourly and deletes terminal task trios older
than 48 hours. Update the description to reflect actual retention policy.
matrix.md: add step 6 to the Provisioning flow section documenting that
hive-c0re restarts hive-matrix-daemon immediately after writing the
access_token (fix for issue #1329). Previously the doc stopped at token
write; the restart + .path-trigger fallback interplay was undocumented.
