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.

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/secrets.md`](../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.

```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, and remove the token:

```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
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`](../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.

```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).

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

```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 · Ruth

hive-c0re creates no agent at startup. You create ruth, the manager agent,
like any other: open the swarm UI start page and click 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.

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 · Matrix

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

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

## 6 · Your first agent

Create it from 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)

## The hive dashboard

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