7b5400ecb8
Permission::default_for and hive-sh4re's MANAGER_AGENT are gone: every agent with no permissions key holds Permission::DEFAULT, ruth included. The agent-name parameters that only fed default_for go with it (permissions::effective, HiveCopy::before_read/after_read and their callers). swarm-controller seeds the grant ruth held by name: at start, a declared ruth whose permissions are unset gets DEFAULT plus manage_root_agent written into her key, once, logged. A set key is never touched. It is a one-shot to delete once every swarm has passed it. The swarm UI setup assistant opens the create form with manage_root_agent checked, so a new ruth is created with the grant. permissions_import no longer adds ruth to the import or splits her default. Docs and help text no longer say ruth holds the grant by default; swarmctl-cli.md regenerated.
155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# 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.
|
|
|
|
## 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).
|