diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 4ae6756f..a30ffbb7 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -3,10 +3,10 @@ What's left to do by hand after the first `nixos-rebuild switch` of the [README's all-local quick start](../../README.md#quick-start-an-all-local-swarm) — from a freshly built host to your first agent. Do the steps in order; -each one assumes the ones before it. +each one assumes the ones before it. Step 0, the NixOS flake, module and +required options, is [`nixos.md`](nixos.md). -Every command runs as **root on the host**. The flake input, module import -and required options are in [`nixos.md`](nixos.md). +Every command runs as **root on the host**. > **Not all-local?** Each step says which host it runs on. A split swarm > also has credentials you can't generate where they're read — each @@ -73,15 +73,14 @@ It prints a generated password once — record it. Keep both flags: Fix either afterwards with `swarmctl user update mara --add-group admins --email …`. Details: [`swarm/sso.md`](../swarm/sso.md). -The swarm UI is now at `https:///`. The name resolves on the -box itself through `/etc/hosts`; from anywhere else it needs a real DNS -record. → [`swarm/ui.md`](../swarm/ui.md) +## 3 · Swarm UI login -## 3 · Forge admin +Open `https:///` and sign in with the account from step 2. The +name resolves on the box itself through `/etc/hosts`; from anywhere else it +needs a real DNS record. → [`swarm/ui.md`](../swarm/ui.md) -Sign in to the forge once through SSO — that first login creates your -forge account under the same username. Then, _on the swarm-controller's -host_: +Signing in to the forge once through SSO creates your forge account under the +same username. Then, _on the swarm-controller's host_: ```bash swarmctl forge make-admin mara @@ -93,14 +92,14 @@ SSO login asks for its forge password once, to link the two. Agents learn your pronouns from the **Pronouns** field of your forge profile settings. Leave it empty and agents refer to you by name only. -## 4 · Ruth +## 4 · Clippy, then ruth -hive-c0re creates no agent at startup. You create ruth, the manager agent, -like any other: open the swarm UI start page and select the paperclip, which -opens the create form with `ruth` filled in and the `manage_root_agent` -permission checked: that permission mounts the other agents into her -container so she can recover them. The form declares her, creates her -config repo and deploys her to the hive you pick. +hive-c0re creates no agent at startup. On the swarm UI's start page, the +paperclip (clippy, the setup assistant) offers to set up ruth, the manager +agent. Select it: it opens the create form with `ruth` filled in and the +`manage_root_agent` permission checked. That permission mounts the other +agents into her container so she can recover them. The form declares her, +creates her config repo and deploys her to the hive you pick. The swarm declares a new agent `paused`, so without a further step ruth runs but drives no turns. Open `/agents` in the swarm UI and set her `up` from her @@ -110,9 +109,14 @@ On a hive that already has a ruth container from an earlier release, create her once the same way, so that her config repo and store identity exist. The container keeps starting with the hive meanwhile. -## 5 · Your first agent +## 5 · Ask ruth for further help -Create it from the swarm UI, or: +From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the +message box under her terminal. She is the manager agent: her MCP surface is the +privileged one that configures agents, and she can recover the others. Changes to +an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../agent-lifecycle/agent-roster.md) + +To create an agent yourself instead, use the swarm UI, or: ```bash swarmctl agent create iris --hive pr1ma @@ -127,23 +131,8 @@ Later config changes are PRs on `agent-configs/iris`; you merge them on the forge, and the merge deploys them. → [`agent-lifecycle/config-changes.md`](../agent-lifecycle/config-changes.md#config-changes) -## The hive dashboard +## After setup: use the swarm UI -The per-hive dashboard answers on `.hives.`, behind -authelia: log in with the `admins` account you created above. The hive's -own domain redirects there. - -→ [`networking/gateway.md`](../networking/gateway.md#dashboard-access) - -## Day to day - -```bash -hivectl list-agents # this hive's agents, status, rev -hivectl agent restart # stop + start, no rebuild -hivectl agent watch # follow its live event stream -hivectl agent choom # interactive claude session in its container -hivectl open # this hive's dashboard (or: forge, matrix) -``` - -Every verb: [`tools/hivectl.md`](../tools/hivectl.md) · -[`tools/swarmctl-cli.md`](../tools/swarmctl-cli.md). +Day-to-day operation happens in the swarm UI at `https:///`: +agents, hives, jobs and messages. Swarm-level operations take over from the +per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../swarm/ui.md)