vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs/setup: ruth needs a store identity and a rebuild, not a hand-made forge user

Browse source 
The rewritten ruth step skipped her store identity, without which
neither the backfill nor her container's fetch can reach her token. With
the backfill now creating a missing forge user, two commands cover her:
swarmctl agent mint-identity ruth --hive <hive>, then hivectl agent ruth
rebuild so hive-c0re hands the identity to her container.

Refs #3782
This commit is contained in:
atlas 2026-09-24 17:39:14 +02:00 • committed by mara
commit 3ee5a960b4
3 changed files with 26 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/getting-started/setup.md
View file

@ -24,18 +24,30 @@ operator has to place, and where.
### 1 · Forge
hive-c0re no longer creates agent forge users or mints agent tokens.
swarm-controller does, for every agent that holds a store identity: a pass
at start and every five minutes creates the forge user if it's missing,
then mints the token into the swarm secret store, where the agent fetches
it under that identity. An agent created with `swarmctl agent create` gets
its identity then. Ruth doesn't: hive-c0re creates her on its own at
startup, so she needs her identity minted by hand, once.
```bash
# hive-c0re no longer creates agent forge users or mints agent tokens:
# swarm-controller does, for agents created at swarm level
# (`swarmctl agent create`), and stores the token in the swarm secret store,
# where the agent fetches it. An agent that only ever existed on this hive —
# ruth's bootstrap, or the hive's own spawn-approval flow — gets no forge
# user from anything yet. Create that user in the forge's admin UI; once the
# agent has a store identity (`swarmctl agent mint-identity`), swarm-controller
# mints its token within five minutes, or at once with:
swarmctl agent mint-forge-token ruth
# On the swarm-controller host: give ruth her store identity. <hive> is the
# name of the hive she runs on.
swarmctl agent mint-identity ruth --hive <hive>
# On ruth's hive: re-apply her container config, which is when hive-c0re
# hands the new identity to the container.
hivectl agent ruth rebuild
```
You don't need to do anything else. The controller's next pass creates
ruth's forge user and mints her token, and her container fetches it within
about ten minutes. `swarmctl agent mint-forge-token ruth` skips the wait for
the pass. A hive without a swarm secret store has no path to a forge token
for ruth at all.
Swarm SSO creates the human operator's own forge account instead of
a manual `hivectl` step — see _Swarm SSO_ below (`swarmctl user add`).