docs: sort the top-level directories into five sections by what the reader wants
Every docs directory moves under 1-getting-started, 2-handbook, 4-implementation or 5-project; the options reference (section 3) comes from the website and has no directory here. trust-boundary stays whole under the handbook for now. web-ui, swarm and tools split between handbook and implementation, and the command-line references move to 2-handbook/reference. Links, path references in code and nix, and the docs index follow the moves; no page content changes.
This commit is contained in:
iris
mara
parent
53ccbcb4b3
commit
6739bb903d
1 changed files with 736 additions and 701 deletions
|
|
@ -1,138 +0,0 @@
|
|||
# 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)
|
||||
Loading…
Reference in a new issue