Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/swarm/forge-accounts.md
2026-11-17 06:48:05 +01:00

122 lines
6.5 KiB
Markdown

# Forge accounts: hives and agents
How swarm-controller gives each hive a read-only forge account and each agent
its own user and token, and where each token lives. The operator's view of the
forge is [the forge page](../../2-handbook/swarm/forge.md).
## How a hive reads the forge
Each hive in swarm-controller's hive directory has its own forge account,
`hive-<hive>`. swarm-controller creates it, makes it a member of the `hives`
team in `agent-configs`, and mints one token named `swarm-hive` into the
swarm secret store at `swarm/hives/<hive>/forge/token`. The team has read
permission on `repo.code` and `repo.pulls` of every repo in the org,
including repos created later. A pass at start and every five minutes
creates what's missing and re-mints a token that's missing or no longer
matches the forge. A pass whose store or forge reads fail queues nothing, so
an outage never rotates every hive's token.
swarm-controller refuses to create an agent whose name starts with `hive-`:
these accounts own that prefix. An agent that already had such a
name keeps it, so the accounts are also told apart by email. swarm-controller
creates the hive's account with the email `hive-<hive>@hives.hyperhive.local`
and refuses an account by that name with any other email: it never adds an
agent's account to the team or mints a token for it. An agent's own forge
account setup refuses the hive's account the same way.
hive-c0re reads the token with `forge::reader_token()`, under the hive's own
store certificate, every time it reads the forge. A hive whose store holds
none reads nothing. These reads go through it, and none of them needs a local
forge container:
- cloning and pulling `/knowledge`
The hive builds nothing, so no nix process reads the forge as the hive's
account. hive-c0re hands the token to each `git` command it runs
(`http.extraHeader`) and keeps no copy on disk. A hive whose store holds no token
reads nothing private from the forge. This also holds on a hive with no forge
container.
Roll a change to any of this out store host first (its granter writes the
controller's grant on `swarm/hives/+/forge/token`), then the controller host,
then the hives. A hive that starts before its token exists reads nothing, and
builds nothing, until the controller's next pass.
## A hive that leaves the roster
A hive dropped from `swarm.hives` keeps the credentials above until
swarm-controller cuts it off (`forge::hive_cutoff`). The roster is the
`SWARM_CONTROLLER_HIVES` env var, read at start, so a removal takes effect at
the next controller start. On every pass, swarm-controller cuts off each hive
that has a forge account with the hive email, or a cert-auth role
`hive-<hive>`, and isn't in the roster. A role named `hive-agent-<agent>`
belongs to an agent and never matches.
For each such hive, in this order:
1. delete its `swarm-hive` forge token,
2. remove its account from the `agent-configs/hives` team,
3. delete the store secret `swarm/hives/<hive>/forge/token`,
4. delete the cert-auth role `hive-<hive>`.
The role goes last because it marks that work remains: a step that fails
leaves the role, and the next pass runs every step again. A step that finds
nothing to remove does nothing, so a finished hive costs a few reads per pass.
The pass logs one `hive is not in the roster: its credentials are revoked` line
per hive with what it removed, and a warning for a hive whose cut-off failed.
The forge account stays, so a hive put back in the roster gets its token and
team seat from the pass above and its role from the store access
swarm-controller writes at start.
Nothing happens when the roster didn't load. An unset or unparseable
`SWARM_CONTROLLER_HIVES`, and a roster with no hive, read the same as a removal of every
hive, so the controller logs an error at start and skips the
cut-off. The attic pull token and the OIDC client secret under
`swarm/hives/<hive>/` stay, as does the forge account itself.
## Per-agent forge accounts
Each agent gets its own Forgejo user and access token. swarm-controller
creates the user when it creates the agent, and mints one token named
`swarm-agent` with the admin API into the swarm secret store at
`swarm/agents/<agent>/forge-token`. A pass at start and every five minutes
covers every agent with a store identity: it creates a missing forge user and
re-mints any token that's missing or no longer matches the forge;
a rotation deletes the old `swarm-agent` token first, so each agent holds at
most one. The agent fetches the token under its own store certificate into
`/run/hive-agent-forge-token/token` (`nix/agent-modules/forge-token.nix`),
and `hive-forge`, the git credential helper, the `forge_notify` poller and
the avatar sync read it from there, falling back to `<state>/forge-token`,
the file hive-c0re wrote before. hive-c0re no longer creates agent users or
mints agent tokens. swarm-controller deletes the `hyperhive-<unix-seconds>`
tokens it left behind, for each agent whose current `swarm-agent` token is
live; tokens of other names are never touched.
Two things live in the `agent-configs` Forgejo organization:
- A config repo per agent (`agent-configs/<name>`). The
agent is a **read collaborator on its own** repo: it clones it and
opens config PRs through the AGit flow (`hive-forge pr create --agit`),
which needs no push access. `main` is
branch-protected by swarm-controller: the merge and approval
allowlists are the `operators` team, and the agent can neither push
`main` directly nor self-merge. An operator's merge in the Forgejo UI
deploys the merged commit (see
[config-changes.md § Config changes](../../4-implementation/agent-state/config-changes.md#config-changes)).
hive-c0re pushes nothing to this org and reads nothing from it.
Repos stay private, so an agent can't read another
agent's config. The agent's **persistent meta flake input** is this repo's `main` head,
pinned by sha in `internal/meta` (`agent-<n>.url =
git+<forge>/agent-configs/<n>.git?rev=<sha>`; see
[config-changes.md § Meta flake](../../4-implementation/agent-state/config-changes.md#meta-flake)).
The `hive-forge` CLI (separate workspace crate, see
[`README.md`](../../README.md) file map) wraps the Forgejo REST API
with the per-agent token; agents call it for issue / PR / comment
ops as if it were a peer. All REST calls across the workspace
(`hive-forge` verbs, hive-c0re provisioning, this poller) go through
the typed `forgejo-api` crate; only non-`/api/v1` web-router routes
(attachment / artifact downloads, log streaming) and the poller's
enrichment fetches of server-provided subject URLs stay on raw
reqwest.