vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
atlas 5c658e9bcf docs/ci: stagger the GC we recommend, and say that temp roots stop at a store boundary 
The nightly GC this page tells operators to configure is what #4019 is
about: a collection that lands on the same wall clock as CI. Two gaps in
the guidance rather than one.

`dates = "daily"` with no randomization puts the collection at the same
time every night, so whatever else runs nightly meets it every night.
`randomizedDelaySec` spreads it; the value is nixpkgs' own example for
that option, and the option feeds `RandomizedDelaySec` on the timer.

The overlap itself does not fail a build on a single host — the runner
builds through the host nix-daemon (`hive-ci.nix` disables its own and
bind-mounts the socket), so an in-flight build's temp roots are held by
the daemon a host GC talks to. What it does cost is wall time: the first
build after a collection rebuilds what the collection deleted. That is
the every-run version of the same cause and it is what the comment now
says.

The Remote builders paragraph covered disk space only. Temp-root
protection is per-daemon, so it does not span two stores: a collection
on the builder is not aware of a coordinator build waiting on a path
there. Stated as the reason to stagger the two hosts' windows rather
than give them the same `dates`.

Deliberately not claiming this fixes the failure in #4019. That one
observed a missing build input with a remote builder in play, and
distinguishing "the collector deleted it" from "it was never in that
store" needs a correlated reading on both hosts during a live window,
which has not been taken. This is the half that is knowable from the
tree: our own recommendation is what schedules the collision.
2026-09-07 15:30:01 +02:00
..
agent-lifecycle docs: say what these things are, not where they used to be 2026-09-07 15:06:12 +02:00
crates docs: rename docs/components to docs/crates 2026-08-12 13:32:55 +02:00
getting-started treefmt: apply prettier 2026-09-02 15:25:07 +02:00
integrations deploy: split the forge's host decisions out of swarm.forge 2026-09-07 14:24:52 +02:00
networking deploy: split the forge's host decisions out of swarm.forge 2026-09-07 14:24:52 +02:00
process docs: say what these things are, not where they used to be 2026-09-07 15:06:12 +02:00
scheduler docs/ci: stagger the GC we recommend, and say that temp roots stop at a store boundary 2026-09-07 15:30:01 +02:00
swarm deploy: move grafana's datasources, plugins and socket out of swarm.grafana 2026-09-07 14:24:52 +02:00
tools deploy: split the homeserver's host decisions out of swarm.matrix 2026-09-07 14:24:52 +02:00
trust-boundary treefmt: apply prettier 2026-09-02 15:25:07 +02:00
turn-loop claude-settings: enable native auto-compact as a mid-turn safety net 2026-09-07 13:51:33 +02:00
web-ui deploy: split the homeserver's host decisions out of swarm.matrix 2026-09-07 14:24:52 +02:00
README.md docs: pilot split of github.md into operator-facing + collapsed implementation 2026-09-02 20:38:02 +02:00
web-ui.md treefmt: apply prettier 2026-09-02 15:25:07 +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? → getting-started/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, terminal-rendering) 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).

Agent lifecycle

Trust boundary & security

Accounts & integrations

  • How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → integrations/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? → integrations/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? → integrations/github.md (operator content up top; the gh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom).
  • What is /knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? → integrations/knowledge.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? → networking/gateway.md.
  • How does DNS resolution work in agent containers? What's the bridge network for? → networking/network.md.
  • How do I connect two hives into a swarm? → swarm/ (peer hives, TLS trust).
  • Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → networking/snapshot-store.md.

Scheduler, CI, observability

  • What is the job queue, as a general idea (not hive-c0re specifics)? → scheduler/jobq.md — operator-facing, no implementation detail.
  • How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals? → scheduler/coordinator.md.
  • How does the CI runner work? What's the auto-registration flow? → scheduler/ci.md.
  • How do I export Claude Code metrics (tokens, cost, tool calls) to Prometheus/Grafana? → scheduler/observability.md.

Crate reference

  • What does a specific Rust crate do, on its own terms? → crates/ — every workspace crate's own README.md, one level up from source (hyperhive#3051); the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions