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

First-run setup

What's left to do by hand after the first nixos-rebuild switch of the README's all-local quick start — from a freshly built host to your first agent. Do the steps in order; each one assumes the ones before it. Step 0, the NixOS flake, module and required options, is nixos.md.

Every command runs as root on the host.

Or just run swarmctl setup. It walks the steps below interactively as root: it checks where you stand first, so a rerun continues where it stopped; 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, such as the store's keys and root token, under a ⚠️ warning until you confirm 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. Steps with no verb yet print their command and wait for you. The sections below are the same steps by hand.

Run swarmctl setup status at any point to see how far you have got. It lists the hand steps below, numbered 1 to 10 in the order the sections run them, marks each done, not done or unknown, and names the next one. It changes nothing.

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.

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 iris --hive firsthive

The controller provisions iris's identity, forge user and config repo (agent-configs/iris, from the default template), then has the hive build and start the container. 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/iris; 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