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 1d261b3fed swarm-nats: give the queue a name, a bao-issued leaf, and require TLS 
The queue listened in plaintext on 4222, reached by bridge IP or loopback,
and nothing in-tree opened it to another hive. It now has a name, serves a
certificate for that name alone, and refuses clients that do not speak TLS.

- `swarm.nats.domain`, default `nats.<swarm.domain>`, a sibling name like
  `swarm.bao.domain`. The queue host answers it via `gateway.localNames`;
  every other hive resolves it through the operator's DNS, as for bao.
- `pki/roles/swarm-nats` allows that one name (bare domain, no subdomains,
  IPs or localhost, server flag). A `swarm-nats` cert-auth role and policy
  may only `update` `pki/issue/swarm-nats`, written by
  `swarm-bao-nats-tls-policy`. The login leaf is minted by glue-bao-tls and
  paired by glue-nats-bao-identity. `deploy.bao.natsCommonName` is reserved
  as a hive name.
- `swarm-bao-nats-tls` issues the leaf into a directory bound read-only into
  the container, restarts nats when it rotates, and re-runs daily.
  It joins glue-bao-readers-policy-order, so it is ordered after its policy
  unit (`after` and `wants`, never `requires`) where the store is on the
  same host. The policy unit joins the store's journald list.
- nats gets `tls {}`, with the key via `LoadCredential`, and no
  `allow_non_tls`. `validateConfig` is now off in every mode, because the
  build-time check loads a leaf that only exists at runtime.
- 4222 is also open on `wg-hive` when the host is on the mesh, never
  host-wide.
- `statusPublish.natsUrl`, `queue.agentNatsUrl`, the controller's URL under
  `singleHostSwarm`, and the auth responder all dial
  `tls://<swarm.nats.domain>:<port>`. swarm-queue-client hands its CA file
  to the NATS connection too, so hive-c0re and the controller trust the
  leaf's root.
- docs/swarm/README.md: the queue URL and the one DNS record a multi-host
  swarm needs.

module-eval-nats-tls pins the role, the policy, the served leaf, the
firewall, the ordering, and a scan of every `*_NATS_URL` and the
responder's URL across the host and its containers.

Closes #4626
2026-09-24 17:26:31 +02:00
..
agent-lifecycle docs: fix markdown indent treefmt wants after removing the ownership-checks bullet 2026-09-24 12:24:32 +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 docs/setup: point at the bootstrap policy file instead of inlining a copy (#4698) 2026-09-24 15:55:38 +02:00
integrations matrix: one sender account and one sender token per hive 2026-09-20 22:07:16 +02:00
networking docs: suppress reviewed write-good.Passive false positives 2026-09-20 16:24:11 +02:00
process docs, hive-c0re: retire prose describing the removed get_loose_ends target 2026-09-24 12:24:32 +02:00
scheduler docs: retire the agent hierarchy from every page that described it 2026-09-21 22:08:47 +02:00
swarm swarm-nats: give the queue a name, a bao-issued leaf, and require TLS 2026-09-24 17:26:31 +02:00
tools subagent: make interrupt cancel a goal run, not just its turn 2026-09-23 23:14:13 +02:00
trust-boundary matrix: one sender account and one sender token per hive 2026-09-20 22:07:16 +02:00
turn-loop docs: retire the agent hierarchy from every page that described it 2026-09-21 22:08:47 +02:00
web-ui docs: describe the flat container list, not a dormant tree 2026-09-21 22:56:56 +02:00
README.md docs: retire the agent hierarchy from every page that described it 2026-09-21 22:08:47 +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 services.hyperhive.agent.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's 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