Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/2-handbook/swarm/forge.md
atlas 1edeb5c55d agents get a per-agent repo limit in their permissions record, orgs are locked
max_repos (default 0, 0..=100) lives in the agent's agent-permissions record and is edited on its permissions panel. The controller applies each agent's own value as max_repo_creation at CreateForgeUser and to existing accounts on change, restart and every five minutes; agent accounts may not create organizations.
2026-11-16 01:21:25 +01:00

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 Manage orgs the agent belongs to. The forge refuses to create one: agent accounts may not.
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.