hyperhive/docs/1-getting-started/setup.md

First-run setup

What's left after the first nixos-rebuild switch of the README's all-local quick start — from a freshly built host to your first agent. Step 0, the NixOS flake, module and required options, is nixos.md. Everything after that takes one command, which you run as root on the host:

swarmctl setup

It walks the ten steps interactively, in order. It checks where you stand first, so a rerun continues where it stopped. It shows Step n of N, prompts for what each step needs, shows a running action as one live line, and prints the secrets you must record under a ⚠️ warning until you type yes to say you stored them. A step this host can't do, because it doesn't run that service, names the deploy option it needs and the host to run swarmctl setup on.

A session that starts at the SSO account, with the store already set up, looks like this:

# swarmctl setup
swarmctl setup: 10 steps, 4 left to do
  ✔  1  secret store initialised
  ✔  2  secret store unsealed
  ✔  3  granter bootstrapped
  ✔  4  granting units active
  ✔  5  store unsealed after the granting units
  ○  6  SSO account in the admins group
  ○  7  first swarm UI and forge login
  ○  8  forge site admin
  ○  9  ruth created and up
  ○ 10  another agent (optional)

Step 6 of 10: SSO account in the admins group   (4 left, this one included)
no enabled user in the "admins" group; the placeholder is disabled
Your SSO account is made in the `admins` group, which the swarm UI gates on.
Username: mara
Display name [mara]: Mara
Email address (the forge needs one): mara@example.com
✔ added mara
⚠️  Its generated password follows. It is shown once and stored nowhere.

password: …

Type `yes` once you have stored the password: yes

Steps the tool can't do for you print their command and wait: the unseal under the shamir seal, the restart after the granter, and the browser login.

Run swarmctl setup status at any point to see how far you have got. It changes nothing, and it works from a script: it exits 0 when every step it can see has finished.

# swarmctl setup status
🏗️  setup: 6/8 steps done  ███████░░░  ❓ 2 unknown

✅   1  secret store initialised
✅   2  secret store unsealed
✅   3  granter bootstrapped                     the granting units log in through it
✅   4  granting units active                    2 units
✅   5  store unsealed after the granting units
👉   6  SSO account in the admins group          no enabled user in the "admins" group; the placeholder is disabled
      ↳ setup.md § 2: `swarmctl user add <name> --email <address> --group admins`
❓   7  first swarm UI and forge login           unknown (not observable: a browser login leaves nothing to read)
❓   8  forge site admin                         unknown (not observable: the controller has no read route for it; `forge make-admin` is safe to re-run)
⬜   9  ruth created and up                      ruth is declared paused
✅  10  another agent [optional]                 1 besides ruth

next: step 6, setup.md § 2: `swarmctl user add <name> --email <address> --group admins`

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 host's mTLS identity at the secret store. Read 2-handbook/swarm/credentials.md first; it says which files you place, and where.

The steps by hand

The sections below are the same steps, one command each. Use them to know what a step does, to script one, or to redo one. Do them in order; each one assumes the ones before it.

1 · Secret store

On the host running swarm-bao. Everything else fetches its credentials from the store, so it comes first.

swarmctl bao init

It prints the unseal (or, under the default pkcs11 seal, recovery) keys and the root token once, and stores none of them: not in a file, and the root token is never in a process's argument list (so not in ps). Record them off this host before you do anything else. It refuses an initialised store, and works from any host that can reach the store and has bao on PATH; the wrapper installed on the store host already knows the store's address and CA.

Then bootstrap the granter, the one principal that writes every swarm-* policy and role from then on. This is the only step that needs the root token. Run it as root on the host running swarm-bao:

swarmctl bao grant-bootstrap     # prompts for the root token, input hidden

It writes the bao-bootstrap policy, places a 24h grant token for swarm-bao-granter-role and restarts that unit. The token comes from the hidden prompt, or from stdin when stdin isn't a terminal; never from an argument or environment variable. If the granter exists already, it says so and does nothing. To do both steps in one go, without re-typing the root token, run swarmctl bao init --and-grant instead (it needs the pkcs11 seal, which unseals itself).

If the host running swarm-bao has no swarmctl (the controller runs elsewhere), the granting units print the equivalent bao commands when the store refuses them.

Check systemctl status swarm-bao-granter-role logs Uploaded policy: bao-granter, then restart the granting units that failed while they waited. The granter unit deletes the token itself after a successful run:

systemctl reset-failed 'swarm-bao-*-policy.service' swarm-bao-agent-pki.service
systemctl restart 'swarm-bao-*-policy.service' swarm-bao-agent-pki.service
systemctl status swarm-bao-controller-policy   # Uploaded policy, Data written to: auth/cert/certs/swarm-controller

⏱️ A first attempt right after a rebuild may fail with local node not active while the store comes up; the units retry every 30s for a day.

With the default pkcs11 seal the store unseals itself from here on. With deploy.bao.seal = "shamir", run bao operator unseal after every restart. What the granter is, why it's root-equivalent, and the store's TLS: 4-implementation/swarm/bao.md.

2 · Your SSO account

On the host running authelia. Until this runs, auth.<swarm.domain> serves a login page that refuses everyone: its only subject is a placeholder marked disabled.

swarmctl user add mara --display-name Mara --email mara@example.com --group admins

It prints a generated password once — record it. Keep both flags:

• --group admins — the swarm UI and other operator surfaces gate on it. Without it you log in fine and are then refused.
• --email — the forge won't create an account without one.

Fix either afterwards with swarmctl user update mara --add-group admins --email …. Details: 2-handbook/swarm/sso.md.

3 · Swarm UI login

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. → 2-handbook/swarm/ui.md

Signing in to the forge once through SSO creates your forge account under the same username. Then, on the swarm-controller's host:

swarmctl forge make-admin mara

If the forge already has a local account with your username, the first 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 · Clippy, then ruth

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 card.

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 · Ask ruth for further help

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. → 2-handbook/agents/agent-roster.md

To create an agent yourself instead, use the swarm UI, or:

swarmctl agent create <name> --hive firsthive

The name is yours to choose; it has no meaning to the swarm. The controller provisions the agent's identity, forge user and config repo (agent-configs/<name>, from the default template), then has the hive build and start the container. The hive builds from a copy of hyperhive on the swarm's own forge: the controller mirrors it there as hyperhive/hyperhive on a fresh swarm, so the first agent needs no extra step (see nixos.md). It returns once the scheduler queues the job — watch the swarm UI's job view for progress.

Later config changes are PRs on agent-configs/<name>; you merge them on the forge, and the merge deploys them. → 2-handbook/agents/config-changes.md

After setup: use the swarm UI

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. → 2-handbook/swarm/ui.md