mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: order the setup steps bao, sso account, swarm ui login, clippy then ruth

Browse source 
Follows the order and short steps asked for in #6021: bao, SSO account, swarm UI login, clippy then ruth, then ask ruth for further help (new step 5). The old forge-admin step moves into the swarm UI login step.

Ends the page after step 5 with a pointer to the swarm UI. The hive dashboard and hivectl sections are dropped because they are deprecated in favour of swarm-level ops (mara, #114764).
This commit is contained in:
atlas 2026-11-04 19:53:42 +01:00
commit adaabe6f51
1 changed files with 27 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -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://<swarm.domain>/`. 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://<swarm.domain>/` 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 `<hive>.hives.<swarm domain>`, 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 <name> restart # stop + start, no rebuild
hivectl agent <name> watch # follow its live event stream
hivectl agent <name> 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://<swarm.domain>/`:
agents, hives, jobs and messages. Swarm-level operations take over from the
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../swarm/ui.md)