From 757e6fc1a79b972a346530b0cc8a3f3f9349520b Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 11 Nov 2026 22:50:32 +0100 Subject: [PATCH] docs: the swarm decides who is on the roster, so that text moves to the swarm page The agent roster page opened with how an agent comes to exist (the identity store, swarmctl, the swarm UI, the ruth archetype), which is the swarm's doing. That text now sits in a "Who is on the roster" section of the swarm page, and the roster page keeps what is a hive's and an agent's: the hive's own list, who may reach whose state, and that the manager is a normal agent. --- docs/2-handbook/agents/agent-roster.md | 29 ++++++++++++-------------- docs/2-handbook/swarm/README.md | 16 ++++++++++++++ 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/2-handbook/agents/agent-roster.md b/docs/2-handbook/agents/agent-roster.md index 58fe79daa..01ba87dc7 100644 --- a/docs/2-handbook/agents/agent-roster.md +++ b/docs/2-handbook/agents/agent-roster.md @@ -3,16 +3,14 @@ Agents are a **flat set**: no agent manages another by position. The `manage_root_agent` permission is the one grant that reaches another agent. -## Who is on the roster +## The hive's list of agents -The swarm decides. An agent exists in the swarm if and only if it has an identity -in the swarm's authelia identity store, which `swarmctl agent create` or the -swarm UI writes once. `GET /api/agents` on the swarm controller lists them. - -Each hive also keeps a small file of its own, `topology.json`, with the agents -this hive has state or config for. You never edit it: the hive rebuilds it from -what it sees locally, so a hand edit is overwritten, and one that doesn't parse -stops the rebuild until you fix it. It matters for one thing, covered next. +Which agents exist is the swarm's to decide: +[who is on the roster](../swarm/README.md#who-is-on-the-roster). Each hive also +keeps a small file of its own, `topology.json`, with the agents this hive has +state or config for. You never edit it: the hive rebuilds it from what it sees +locally, so a hand edit is overwritten, and one that doesn't parse stops the +rebuild until you fix it. It matters for one thing, covered next. ## Who may reach whose state @@ -20,16 +18,15 @@ An agent holding no permission sees its own directories and nothing else. An agent holding `manage_root_agent` gets every other agent's `state` directory on this hive mounted read-write at `/agents//state`, never `config` or `harness`. It's the only grant that reaches another agent's state. Ruth, the -root agent, holds it, and the swarm UI's setup assistant creates her from the -[`ruth` archetype](../swarm/archetypes.md#the-built-in-archetypes), which grants it and sets her model to `sonnet`. A ruth created before the archetype keeps her model; set `sonnet` in her inference settings in the swarm UI if wanted. The -mounts follow the roster: an empty file means no mounts until the next rebuild. +root agent, holds it (the swarm creates her from the `ruth` archetype, see +[who is on the roster](../swarm/README.md#who-is-on-the-roster)). The mounts +follow the hive's list: an empty file means no mounts until the next rebuild. ## The manager is a normal agent -`ruth` differs from other agents in her name and in that grant. You create her -like any other agent, from the swarm UI or `swarmctl agent create`; the hive -creates nothing at boot. Her permissions, prompt and tools work as for every -agent, and destroying her is as final as for any other. +`ruth` differs from other agents in her name and in that grant. Her +permissions, prompt and tools work as for every agent, and destroying her is as +final as for any other. How the hive reads and rebuilds the file, the wire protocol and the prompt blocks: [`roster.md`](../../4-implementation/agent-state/roster.md). The operator/agent diff --git a/docs/2-handbook/swarm/README.md b/docs/2-handbook/swarm/README.md index a409cfde7..6d055cc89 100644 --- a/docs/2-handbook/swarm/README.md +++ b/docs/2-handbook/swarm/README.md @@ -100,6 +100,22 @@ socket-directory constraint that governs where `socketPath` may point: The options, wire formats and failure modes of each: [`controller.md`](../../4-implementation/swarm/controller.md). +### Who is on the roster + +The swarm decides. An agent exists in the swarm if and only if it has an +identity in the swarm's authelia identity store, which `swarmctl agent create` +or the swarm UI writes once. `GET /api/agents` on the swarm controller lists +them. A hive creates nothing at boot, so every agent, the manager `ruth` +included, comes from the swarm UI or `swarmctl agent create`, and destroying +one is as final for her as for any other. + +The swarm UI's setup assistant creates `ruth` from the +[`ruth` archetype](archetypes.md#the-built-in-archetypes), which grants her +`manage_root_agent` and sets her model to `sonnet`. A ruth created before the +archetype keeps her model; set `sonnet` in her inference settings in the swarm UI +if you want it. What that grant lets an agent reach on a hive is on the +[agent roster page](../agents/agent-roster.md). + ## Hives: the substrate - **hive** — one host running `hive-c0re` and its agent containers