From ff0a6f1ca3bbcbf02d385235949e0802d33037b0 Mon Sep 17 00:00:00 2001 From: atlas Date: Tue, 13 Oct 2026 01:17:42 +0200 Subject: [PATCH] docs: say that re-creating an undeclared agent leaves it paused `swarmctl agent create` declares an agent the swarm has no declaration for as paused, so ruth needs setting `up` from her card after step 4. Restores the warning to re-create agents before a hive-side change makes a container require a store identity. --- docs/getting-started/setup.md | 5 +++++ docs/swarm/credentials.md | 10 +++++++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index dd7f4791..86866108 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -99,6 +99,11 @@ swarmctl agent create ruth --hive # on the swarm-controller's host hivectl agent ruth rebuild # on ruth's hive: hands her the identity ``` +`agent create` declares an agent the swarm has no declaration for as +`paused`, so without a further step ruth keeps running but drives no turns. +`swarmctl` has no verb for wanted state: open `/agents` in the swarm UI and set +her `up` from her card. + Within about ten minutes the controller creates her forge user and matrix account and mints their tokens into the store, where she fetches them. `swarmctl agent mint-forge-token ruth` skips the wait for the forge token. diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md index 7dfeb09e..c285080e 100644 --- a/docs/swarm/credentials.md +++ b/docs/swarm/credentials.md @@ -113,7 +113,15 @@ swarmctl agent mint-forge-token An agent without a store identity gets no swarm token and keeps using the `forge-token` file in its state dir, if it has one; re-create it with -`swarmctl agent create` to give it one. +`swarmctl agent create` to give it one. The swarm leaves an agent it already +declares as it is. For an agent with no declaration, such as one only its hive +knows about, `agent create` declares it `paused`; set it `up` from its card in +the swarm UI. + +⚠️ **Re-create existing agents before deploying a hive-side change that makes a +container require a credential it may not have.** A container whose store +identity is absent doesn't start (`nix/agent-modules/bao.nix` exits 1), so +create the identities first, setting any newly paused agent `up` as above. **Revoking an agent's queue credential.** Declaring an agent `destroyed` — `PUT /api/hives/{hive}/agents/{agent}/state` — deletes