vinzenz/hyperhive
vinzenz/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
atlas 6aab2ebb65 swarm metrics store: the read API needs Grafana's bearer or an operator session 
The metrics vhost forwarded the store's read API (query, series, labels,
export, vmui, ...) with no credential, so anything that could reach
metrics.<swarm> could read every hive's and agent's metrics. mara ruled on
checked by an auth_request responder, and operators use their authelia
session.

- swarm-metrics-auth (new crate): auth_request responder on the metrics
  store's host. Compares the presented bearer, in constant time, with the
  one stored at swarm/services/<grafana client id>/metrics/bearer, read
  under its own bao leaf and cached for 60s. Static user, the post-#5264
  swarm-logs-auth unit shape.
- swarm-bao-grafana-metrics-bearer: on Grafana's host, creates that bearer
  in bao if absent (create without update, Grafana's existing leaf) and
  writes "Bearer <value>" into the container; the datasource sends it as
  its Authorization header via $__file{}.
- The vhost: read locations take auth_request through a map (a bearer goes
  to swarm-metrics-auth, anything else to authelia, no login redirect);
  vmui takes an authelia session with the login redirect; forceSSL like
  the logs vhost. The authelia subrequest location is renamed from
  /__metrics_push_authz to /__metrics_authelia since it now serves reads.
- Authelia: the collector keeps every path; everyone else is refused the
  collector's push and /metrics paths; group admins is admitted to the
  rest; then deny.
- bao: a swarm-metrics-auth cert role and policy (read on the one leaf),
  its leaf minted by glue-bao-tls, the CN reserved as a hive name, and
  Grafana's grant gains create on the bearer leaf.

Fixes #3596
2026-10-15 10:48:20 +02:00
..
agent-lifecycle docs: rewrite the container load and retired limits prose in active voice for the vale error rules 2026-10-15 08:28:10 +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: say that re-creating an undeclared agent leaves it paused 2026-10-13 08:08:06 +02:00
integrations hive-matrix: run the homeserver in its own netns, behind a unix socket 2026-10-15 09:52:06 +02:00
networking matrix: drop the shared-netns claims the netns move left behind 2026-10-15 09:52:06 +02:00
process swarm metrics store: the read API needs Grafana's bearer or an operator session 2026-10-15 10:48:20 +02:00
scheduler dashboard: the build pages are tabs of the dashboard 2026-10-15 09:50:49 +02:00
swarm swarm metrics store: the read API needs Grafana's bearer or an operator session 2026-10-15 10:48:20 +02:00
tools hive-c0re: the per-agent resource limit override is gone 2026-10-15 08:28:10 +02:00
trust-boundary swarm builder: the all-swarm-services switch turns it on, like every other swarm service 2026-10-15 05:44:37 +02:00
turn-loop fix passive-voice vale errors in docs + hive-otel module-eval test for the new journald receiver 2026-10-13 22:03:15 +02:00
web-ui dashboard: the SW4RM tab is the agents tab 2026-10-15 09:50:49 +02:00
README.md swarm-builder: build each agent config PR head and post a commit status 2026-10-14 03:30:46 +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 swarm online? → getting-started/setup.md (the hand steps after the first switch).
  • 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).

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 swarm's 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 swarm-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.
  • How does the secret store come up, who writes its grants, how's it sealed? → swarm/bao.md.
  • How does an agent get a prompt at set times, and why doesn't it fire twice after downtime? → swarm/schedules.md.
  • How do I set an agent's model or effort from the swarm, and what happens to its own pick? → swarm/inference.md.
  • How will a PR get checked against its repo's own yes/no rules before a full review? → swarm/review-classifier.md (planned, not implemented yet).
  • Does an agent config PR build before it's merged? → swarm/builder.md.

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? How does it register? → 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