Watch
0
0
Fork
You've already forked hyperhive
0

document the hive cut-off

This commit is contained in:
atlas 2026-11-16 22:44:27 +01:00 • committed by mara
commit b6dc46d315
2 changed files with 41 additions and 1 deletions

View file

@ -36,7 +36,7 @@ the rest of the cell says how.
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes |
| `swarm/agents/<agent>/backend-env` | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI | the agent | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start |
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes; deleted when the hive leaves the roster | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
| `swarm/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign, which the operator's per-agent `ssh` switch allows the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |

View file

@ -42,6 +42,39 @@ 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