From 3ee5a960b47bb017321e177e42c196b15e4053a1 Mon Sep 17 00:00:00 2001 From: atlas Date: Thu, 24 Sep 2026 17:39:14 +0200 Subject: [PATCH] docs/setup: ruth needs a store identity and a rebuild, not a hand-made forge user 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 , then hivectl agent ruth rebuild so hive-c0re hands the identity to her container. Refs #3782 --- docs/getting-started/setup.md | 30 +++++++++++++++++++++--------- docs/integrations/forge.md | 3 ++- docs/swarm/credentials.md | 5 +++-- 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 62b8ab01..22580928 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -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. is the +# name of the hive she runs on. +swarmctl agent mint-identity ruth --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`). diff --git a/docs/integrations/forge.md b/docs/integrations/forge.md index 0c598116..83509234 100644 --- a/docs/integrations/forge.md +++ b/docs/integrations/forge.md @@ -52,7 +52,8 @@ Each agent gets its own Forgejo user and access token. swarm-controller creates the user when it creates the agent, and mints one token named `swarm-agent` with the admin API into the swarm secret store at `swarm/agents//forge-token`. A pass at start and every five minutes -re-mints any agent's token that's missing or no longer matches the forge; +covers every agent with a store identity: it creates a missing forge user and +re-mints any token that's missing or no longer matches the forge; a rotation deletes the old `swarm-agent` token first, so each agent holds at most one. The agent fetches the token under its own store certificate into `/run/hive-agent-forge-token/token` (`nix/agent-modules/forge-token.nix`), diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md index 2350bdcf..f05efba3 100644 --- a/docs/swarm/credentials.md +++ b/docs/swarm/credentials.md @@ -97,8 +97,9 @@ its queue connection. The certificate half isn't: the agent gets a fresh leaf and picks it up on its next boot. The forge token needs no such step: `swarm-controller` checks every agent -that has a store identity at start and every five minutes, and mints a token -for any whose stored one is missing or stale. To check one agent now: +that has a store identity at start and every five minutes. For any whose +stored token is missing or stale it creates the forge user if there isn't one, +then mints the token. To check one agent now: ```sh swarmctl agent mint-forge-token