0f39bdaaa4
Account minting, knowledge sync, the archetype refresh, the matrix appservice flow and the SSO secret delivery move to pages under 4-implementation/swarm. Each handbook page keeps what an operator does or sees, with a pointer.
4.1 KiB
Swarm forge (Forgejo)
Private Forgejo instance running in a nixos-container (hive-forge, the
container and CLI name), used as the
swarm's persistent code-collaboration surface (issues, PRs, reviews,
attachments). Configured via services.hyperhive.swarm.forge.* (what the
forge IS to every hive — names, ports, URLs) plus
services.hyperhive.deploy.forgejo.* (what the host running it decides —
which build it runs, how it's served, what it mirrors, where its
host-local secrets sit).
Container
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
handling live in docs/4-implementation/networking/gateway.md; this file owns the
per-agent integration story and the notification pump that wakes
each agent on relevant activity.
Token scopes
Two scope sets:
AGENT_TOKEN_SCOPES (swarm-controller's forge::agent_token, pinned
by a test). swarm-controller mints every agent token with it:
| Scope | Why |
|---|---|
write:repository |
Create, clone, push, delete repos; merge PRs. |
write:issue |
Open / comment / review issues and pull requests (Forgejo namespaces PR conversation under issues). |
write:user |
Edit own profile, create repos under own user. |
write:organization |
Create + manage orgs (lets agents share a forge namespace). |
read:user |
Token-owner endpoint used for self-identification at harness startup. |
write:misc |
Hooks, attachments, the rest of the long tail. |
read:notification |
Poll GET /notifications for unread events. |
write:notification |
Mark notifications read via PATCH /notifications/threads/{id}. |
HIVE_TOKEN_SCOPES (swarm-controller's forge::hive_token, pinned by a
test): read:repository alone, for each hive's read-only account (see
Hive and agent accounts).
Hive and agent accounts
Each hive has a read-only forge account, hive-<hive>, which it uses to clone
and pull /knowledge. Each agent has its own Forgejo user and access token. The
swarm controller creates both and keeps the tokens in the swarm secret store,
so you set up nothing by hand. A token that goes missing or stops matching the
forge is re-minted within five minutes.
Two things live in the agent-configs Forgejo organization:
- A config repo per agent,
agent-configs/<name>. The agent can push config-change branches and open config PRs there, butmainis branch-protected: only theoperatorsteam can merge, and the agent can neither pushmainnor self-merge. An operator's merge in the Forgejo UI deploys the merged commit (see config-changes.md § Config changes). Repos stay private, so an agent can't read another agent's config.
The hive-forge CLI wraps the Forgejo REST API with the agent's own token;
agents call it for issue, PR and comment operations.
How the controller mints, rotates and reads each token, and the team that gives a hive read
access: forge-accounts.md.
Notifications
Each agent runs a small daemon that polls its forge account for unread notifications every 30 seconds and hands each one to the agent as a todo, so an assignment, a review or a comment wakes the agent. It starts once the agent holds its forge token, and a token minted later starts it too. How it formats, de-duplicates and marks notifications read is in the forge notification poller.