hyperhive/docs/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.

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 host's mTLS identity at the secret store, and each hive's telemetry ingest secret. Read swarm/secrets.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.

sudo bao operator init   # keep the keys it prints and the root token OFF this host

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:

sudo -i
read -rs BAO_TOKEN && export BAO_TOKEN          # paste the root token from `bao operator init`
bao policy write bao-bootstrap /etc/hyperhive/bao-bootstrap-policy.hcl
bao token create -policy=bao-bootstrap -ttl=24h -orphan -display-name=bao-bootstrap -field=token \
  | install -D -m 0600 /dev/stdin /var/lib/swarm-bao-bootstrap/grant.token
unset BAO_TOKEN
systemctl restart swarm-bao-granter-role

Check systemctl status swarm-bao-granter-role logs Uploaded policy: bao-granter, then restart the granting units that failed while they waited, and remove the token:

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
rm /var/lib/swarm-bao-bootstrap/grant.token

⏱️ 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: 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 disabled placeholder.

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: 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

3 · Forge admin

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:

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.

4 · Ruth's store identity

hive-c0re creates the manager agent, ruth, on its own at startup — so unlike agents made through the swarm, she has no store identity yet:

swarmctl agent mint-identity ruth   # on the swarm-controller's host
hivectl agent ruth rebuild          # on ruth's hive: hands her the identity

Within about ten minutes the controller creates her forge user and matrix account and mints their tokens into the store, where she fetches them. swarmctl agent mint-forge-token ruth skips the wait for the forge token.

5 · Matrix

Your matrix account comes from SSO. Invite it to the hive Space, and optionally to rooms:

hivectl matrix invite mara
hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'

6 · Your first agent

Create it from the swarm UI, or:

swarmctl agent create iris --hive pr1ma

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. → agent-lifecycle/approvals.md

Optional · Lock the hive dashboard

The per-hive dashboard has no SSO in front of it. To put it behind HTTP Basic auth, set services.hyperhive.gateway.auth.enable = true and add logins:

echo "hunter2" | hivectl gateway create-user mara --password-stdin

→ networking/gateway.md

Day to day

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 approvals pending       # what's waiting on you
hivectl open                    # this hive's dashboard (or: forge, matrix)

Every verb: tools/hivectl.md · tools/swarmctl-cli.md.