mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs/2-handbook/swarm/forge.md
iris 0ae34b1cd0 docs: persistence and config changes become one operator page 
The operator parts of the persistence and config-changes pages merge into
agents/persistence.md. The sqlite tables, state dirs, mounts and migrations move
to 4-implementation/agent-state/persistence.md, and the deploy path, meta flake,
deploy markers, startup migrations, root container, system messages and
autoupdate move to 4-implementation/agent-state/config-changes.md. Links, code
comments and nix comments that named the old sections point at the new pages.
2026-11-11 01:50:35 +01:00

4.1 KiB
Raw Blame History

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, but main is branch-protected: only the operators team can merge, and the agent can neither push main nor self-merge. An operator's merge in the Forgejo UI deploys the merged commit (see persistence.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.