vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
iris 45710ab739 swarm.js: migrate pending-row fallback + queue-summary banner off DagView 
hyperhive#2822/PR#3026 moved swarm.js's per-agent in-flight status off
the rebuild queue. Two other reads of the same rebuild_queue field
survived that PR by design (a different feature, atlas flagged it on
#2985) and are the last DagView/NodeView consumers on the frontend:
queuedOpsByAgent()'s pending-row fallback and the SW4RM queue-summary
banner. Both now read GET /api/jobq/graph (hive-jobq-wire's generic
GraphNode shape) instead, matching the pattern builds.js already
established for <hive-jobq-graph>.

Along the way: DagView no longer carries state/kind fields (removed
in an earlier refactor that pushed roll-up derivation client-side),
so both migrated functions were silently reading undefined fields and
had become permanent no-ops — the pending-badge fallback never lit
and the queue-summary banner never rendered. This restores real
behavior rather than porting broken logic forward.

The queue-summary banner's node-count-vs-group-count question (flagged
on hyperhive#3028 as needing a decision) resolves cleanly: a GraphNode
group root (parent: null) is an ordinary node whose own state already
IS the group's roll-up per hive-jobq-wire's contract, so counting
roots by state is a direct filter, not a parent-chain walk or a
client-side rollup calculation.

Verified the derivation logic against constructed GraphNode fixtures
(multi-step chains, settled history that must not count, Finishing
roots, multi-agent single-DAG groups) before wiring it in — 13/13
checks passed.

docs/web-ui/dashboard.md's Container-row + BU1LDS sections updated to
match.
2026-08-03 20:03:49 +02:00
..
tools docs: add tools/ landing page 2026-08-03 12:57:00 +02:00
turn-loop docs: give turn-loop/ a README.md landing page 2026-08-03 12:55:18 +02:00
web-ui swarm.js: migrate pending-row fallback + queue-summary banner off DagView 2026-08-03 20:03:49 +02:00
agent-hierarchy.md hivectl: rename hivectl agents to hivectl agent <name> <verb> 2026-07-27 19:07:18 +02:00
approvals.md hive-c0re: deliver scheduled prompts via push_todo, not a broker message 2026-08-03 01:08:24 +02:00
boundary.md feat(#2641): sudoless hivectl via a hive-admin group on the host socket 2026-07-22 22:50:27 +02:00
ci.md docs(ci): add a For operators section 2026-08-03 00:30:57 +02:00
conventions.md always-on mark_todos_done: no ToolGroup ever exposed it, blocking every agent 2026-08-03 19:09:38 +02:00
coordinator.md job_queue: declare a node's resources where the node is constructed 2026-08-02 16:29:06 +02:00
forge.md feat(#2642): a github.com notification poller alongside the forge one 2026-07-31 17:23:18 +02:00
gateway.md hivectl: add agent <name> watch to follow live events from the CLI 2026-07-27 21:04:00 +02:00
github.md docs(github): move impl detail below the operator-facing sections 2026-08-02 23:54:55 +02:00
gotchas.md feat(#2693): let the operator pin the claude-code every agent runs 2026-07-27 13:56:28 +02:00
knowledge.md docs: describe the knowledge-change broadcast in the sync-mechanism section 2026-08-02 03:13:04 +02:00
matrix.md refactor: nix/host-modules + nix/agent-modules layout, update doc paths 2026-07-13 22:05:49 +02:00
network.md fix(gateway): resync the gateway's resolv.conf when the host's changes 2026-07-26 18:01:34 +02:00
observability.md feat(#2007): export per-agent container cpu/mem/disk via otel 2026-07-15 22:51:31 +02:00
persistence.md docs: give turn-loop/ a README.md landing page 2026-08-03 12:55:18 +02:00
README.md docs: add a top-level docs/README.md index, point README.md at it 2026-08-03 17:27:43 +02:00
security.md docs(#2754): document the container weights in coordinator/security/persistence 2026-07-27 11:01:36 +02:00
setup.md hivectl: rename hivectl agents to hivectl agent <name> <verb> 2026-07-27 19:07:18 +02:00
snapshot-store.md docs(#2862): document the push side and regenerate the CLI reference 2026-07-31 22:15:37 +02:00
swarm.md docs(#2862): document the push side and regenerate the CLI reference 2026-07-31 22:15:37 +02:00
terminal-rendering.md refactor(#2416): remove the non-pr config-change flow (request_apply_commit / applycommit) 2026-07-15 21:03:52 +02:00
web-ui.md docs(web-ui): add an operator-facing README as the subdir landing page 2026-08-02 23:26:29 +02:00

README.md

hyperhive docs

Depth reference for hyperhive — the substrate, not the pitch (that's the top-level README / website). Every page here stands alone; pick the one matching your task rather than reading top to bottom. For the auto-generated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent), see the options site instead — this tree is prose, that one's generated straight from the module declarations.

Getting started

  • Bringing a fresh hive online? → setup.md (first-run hivectl bootstrap).
  • What does the dashboard look like, and how do I use it? → web-ui/ — the operator-facing starting point; its own sub-pages (shape, dashboard, agent, css-vars) go deeper into implementation.
  • What tools does an agent (or the operator) have available? → tools/ — hivectl (yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).

Dashboard & agent UI internals

Turn loop, config, approvals

  • How does claude get its prompt, and what tools does it have? → turn-loop/ — the loop, binary shape, turn outcomes; sub-pages: claude-invocation, config, mcp.
  • How do config changes flow from manager to operator to container? → approvals.md (two-step spawn, approval state machine, flake.lock validation).
  • What state survives destroy / purge / restart? → persistence.md.

Trust boundary & security

  • What's the operator/agent trust boundary? What's a capability? → boundary.md.
  • Agent trust model, prompt-injection threat model, credential isolation? → security.md.
  • Who can do what to whom — agent hierarchy and privilege? → agent-hierarchy.md.

Accounts & integrations

  • How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → forge.md (the hive's own Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
  • How does the matrix-tuwunel container work? Multiple accounts per agent? → matrix.md (the homeserver); tools/matrix.md for the MCP tool surface and hyperhive.matrixAccounts.
  • How do I give an agent a GitHub account (gh + git push)? How is the PAT injected? → github.md.
  • What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for the exhaustive, auto-generated flag reference.

Networking & swarms

  • What nginx vhosts does the gateway serve? How does matrix discovery work? → gateway.md.
  • How does DNS resolution work in agent containers? What's the bridge network for? → network.md.
  • How do I connect two hives into a swarm? → swarm.md (peer hives, TLS trust).
  • Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → snapshot-store.md.

Scheduler, CI, observability

  • How does the rebuild queue work? What are queue kinds and sources? → coordinator.md.
  • How does the CI runner work? What's the auto-registration flow? → ci.md.
  • How do I export Claude Code metrics (tokens, cost, tool calls) to Prometheus/Grafana? → observability.md.

Process & conventions

  • Naming, commit style, wire protocol, the data-async pattern? → conventions.md.
  • Why does the nspawn flag look like that? → gotchas.md (bind mounts, conf flags, other NixOS/nspawn quirks).
  • What is /knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? → knowledge.md.