mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
damocles 1c3b5e52cf drop the host side of the agent broker send 
Remove the agent-side Send and AckUntil requests, their hive-c0re handlers
(handle_send with its 4 KiB size cap, handle_ack_until) and Broker::ack_until.
Everything that existed only for them goes with them: the OkWarn response
(its sole producer was Send's reserved-name warning), Recv's max parameter
and RECV_BATCH_MAX (the harness never asked for more than one message),
OPERATOR_SEND_REFUSAL, and the MESSAGE_MAX_BYTES / check_size limit (the
reminder timer keeps its own copy of the cap, so its comment is reworded).

Messages.remaining stays on the wire (default on read) because a harness
built before this change still requires it. Update the conventions docs.
2026-11-08 08:56:39 +01:00
..
1-getting-started swarmctl setup status shows where the setup ceremony stands 2026-11-07 17:20:21 +01:00
2-handbook scope the cache access to hive-core: client-side nix copy, daemon trusts only the key 2026-11-08 01:56:55 +01:00
4-implementation report the btrfs-subvolume root in host filesystem metrics 2026-11-08 03:03:49 +01:00
5-project drop the host side of the agent broker send 2026-11-08 08:56:39 +01:00
README.md docs: the handbook follows the three layers: swarm, hives, agents 2026-11-07 12:19:36 +01: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. The docs sit in five sections, by what the reader wants:

  1. Getting started: what hyperhive is, and how to bring one up.
  2. Handbook: running and using a hive and a swarm.
  3. Options reference: every NixOS option.
  4. Implementation: how it works inside.
  5. Project: how the project itself works.

1. Getting started

2. Handbook

Using and operating hyperhive, in the three layers that make it up, plus the accounts an agent can hold outside it. Some pages here still carry implementation detail next to the operator content; sorting those out is later work.

Swarm

The services that exist once per swarm. Start at 2-handbook/swarm/.

Hives

The host a hive runs on and the operator's tools for it. Start at 2-handbook/hives/.

Agents

One agent: its roster entry, state, config and page. Start at 2-handbook/agents/.

External accounts

Accounts outside the swarm that an agent can hold. Start at 2-handbook/external-accounts/.

  • How to give an agent a GitHub account (gh + git push)? how's the PAT injected? → 2-handbook/external-accounts/github.md (operator content up top; the gh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom).
  • How to give an agent GitLab accounts (glab + git push, more than one instance)? → 2-handbook/external-accounts/gitlab.md.

3. Options reference

The autogenerated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent) lives on the website, built from the module declarations: the options site. Nothing of it sits in this tree.

4. Implementation

Agent tools

  • What can an agent do inside its container? bash, subagent, forge, matrix, and the hive-forge, swarm-logs and swarm-metrics CLI references? → 4-implementation/agent-tools/.

Turn loop, scheduler, CI, observability

Networking

Swarm services

Trust boundary mechanics

Web UI internals

Crate reference

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

5. Project

How the project itself works: processes, conventions, design guides.