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 0ff5c8110b swarm-otel: deliver the OIDC client secret through the secret store 
The swarm collector's OIDC client secret only existed where authelia
did: `swarm-otel-oidc-secret.service` copied the minted plaintext out
of authelia's container tree, reachable only because the two share a
host's network namespace. A swarm that placed authelia elsewhere
delivered nothing, and the option's own description said so —
"a deployment that places authelia elsewhere points this at a file it
delivers itself." Same gap as #3853 and #4234, and this is the
swarm-otel twin of #4234's fix for Grafana.

Mirrors PR #4361 (Grafana) almost exactly:

- `swarm-bao-otel-oidc.service` reads
  `swarm/services/<client-id>/oidc/client` out of the store, in every
  deployment, replacing the co-located copy unit outright — one
  delivery route, not two, per the ruling that landed under #4234.
- Client registration moved out of `swarm-otel.nix`'s own `config`
  block (gated on this host running the collector) into
  `glue-swarm-otel-oidc-client.nix` (gated on this host running
  authelia), the same split `glue-grafana-oidc-client.nix` made. It
  was broken the same way: a split deployment registered the client
  nowhere at all, so authelia never minted a secret for the publisher
  to send on.
- The publisher's `services` prefix (write grant in `swarm-bao.nix`,
  hive read grant in `policy::render`) already covers any service's
  path — nothing to add there. `swarm-secret-publisher.nix` only grew
  `serviceClientIds` by one entry.

One judgement call, stated rather than buried: the store-reading unit
renders only where this host holds a client identity
(`deploy.bao.clientCertFile`/`clientKeyFile`), rather than asserting
it the way `swarm-grafana.nix` does. Grafana's local login form is
disabled unconditionally, so a Grafana with no OIDC secret has no way
in at all — that earns a hard refusal. This collector without a
credential still receives every hive's telemetry; only its own pushes
to the stores go out unauthenticated and get refused there, an
already-supported degrade the module's own `haveCollectorSecret` flag
named before this change. So the reading unit follows the shape
`glue-matrix-bao-token.nix` and `glue-queue-agent-credential.nix` use
for their own optional readers: no unit when the identity is absent,
not a build refusal.

Fixtures mirror #4361's: `otelBaoWithAuthelia`/`otelBaoRemoteAuthelia`
are the positive pair (co-located and split, both reading through the
store), `otelNoIdentity` is the negative — no reading unit, no
assertion firing, `clientSecretFile` left null.

Refs #4258
2026-09-14 00:58:58 +02:00
..
agent-lifecycle docs: drop the operator-schedule-target aside from approvals.md 2026-09-11 23:32:45 +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: use the emphasis form treefmt's prettier normalises to 2026-09-11 19:30:17 +02:00
integrations docs: name options by the path an operator can set, not by cfg.* 2026-09-11 13:32:24 +02:00
networking swarm: give agent containers their own queue principal 2026-09-12 10:33:06 +02:00
process docs: name options by the path an operator can set, not by cfg.* 2026-09-11 13:32:24 +02:00
scheduler docs/observability: hive→swarm ingest auth shipped, stop calling it planned 2026-09-11 18:11:19 +02:00
swarm swarm-otel: deliver the OIDC client secret through the secret store 2026-09-14 00:58:58 +02:00
tools subagent daemon: address review on the killed-session docs 2026-09-13 15:15:38 +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 docs: drop the unverified subagent-inheritance claim per mara 2026-09-13 20:29:39 +02:00
web-ui swarm-ui: read-only agent terminal page consuming the swarm term stream 2026-09-13 20:23:51 +02:00
README.md check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +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.

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