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](../../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. Step 0, the NixOS flake, module and
required options, is [`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
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../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.

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

```bash
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. The granter unit deletes the token itself after a
successful run:

```bash
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:
[`swarm/bao.md`](../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`.

```bash
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`](../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. → [`swarm/ui.md`](../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_:

```bash
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. → [`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
```

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/config-changes.md`](../agent-lifecycle/config-changes.md#config-changes)

## 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`. → [`swarm/ui.md`](../swarm/ui.md)