vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
atlas 937289383c Add a credential docs page: current state, target state, the rule between 
The swarm's credential docs say where every file lives. They do not say
whether it should be a file at all, so a discussion about direction has
had nothing to point at and each one re-derived the same table.

This page carries that table with the three columns the target contract
is written in — minter, reader, renewal — plus the column the target is
really about: whether the value is persisted outside the store. Stating
it flatly is the point. All four stored families are plaintext files on
disk, the appservice token twice; every renewal cell reads NONE; no agent
container holds a store identity at all, so the hive reads on its behalf
and writes a file in; and the appservice token has a second, uncoordinated
local mint that can diverge from the published one.

The target section is marked as a target throughout, because its first
line is the one most easily misread as fact: every host needing a store
mTLS certificate is where this is going, while today only the store's own
host auto-mints and swarm-bao.nix calls it the credential an operator
places by hand everywhere else.

The progressive-enhancement rule is stated as a table of questions a
reviewer applies to a pull request rather than as prose, since a rule
nobody can check is a preference. New functionality matches the target
immediately; existing functionality moves stepwise, and the questions
distinguish a step from churn.

Indexed from the docs root and the swarm README. It supersedes
secrets.md when the migration completes — at which point that file is
deleted and this one moves into its place.
2026-09-16 22:41:23 +02:00
..
agent-lifecycle refactor(hive-c0re): drop the request_init_config tool and InitConfig approval 2026-09-14 19:03:44 +02:00
crates check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
getting-started refactor(hive-c0re): drop the request_init_config tool and InitConfig approval 2026-09-14 19:03:44 +02:00
integrations matrix: publish the appservice token from the swarm, not just read it 2026-09-15 20:57:49 +02:00
networking swarm: give agent containers their own queue principal 2026-09-12 10:33:06 +02:00
process refactor(hive-c0re): drop the request_init_config tool and InitConfig approval 2026-09-14 19:03:44 +02:00
scheduler ops: address argus review findings on PR #4433 2026-09-16 00:07:02 +02:00
swarm Add a credential docs page: current state, target state, the rule between 2026-09-16 22:41:23 +02:00
tools subagent: grant claude's Bash when the agent holds the execution group 2026-09-15 18:48:51 +02:00
trust-boundary swarm-otel: deliver the OIDC client secret through the secret store 2026-09-14 00:58:58 +02:00
turn-loop permissions: give the built-in tool list one home, next to ToolGroup 2026-09-15 17:40:27 +02:00
web-ui refactor(hive-c0re): drop the request_init_config tool and InitConfig approval 2026-09-14 19:03:44 +02:00
README.md Add a credential docs page: current state, target state, the rule between 2026-09-16 22:41:23 +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 autogenerated 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's 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's /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, autogenerated 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.
  • Who mints each credential, who reads it, and how does it rotate — and where is that shape headed? → swarm/credentials.md (current state, target state, and the progressive-enhancement rule); swarm/secrets.md for where each file lives today.

Scheduler, CI, observability

  • what's 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 autoregistration 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; the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions