hyperhive/docs/4-implementation/swarm/forge-accounts.md

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.

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.

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 write collaborator on its own repo — it can push config-change branches and open config PRs — but 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). 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).

The hive-forge CLI (separate workspace crate, see 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.