0b7357d4b8
One commit rather than two because they are not independent: the UI's `enable` had the controller's as its literal default, so moving the controller alone would leave the UI's default naming an option that no longer exists. The UI keeps that derivation in its new home — it is a view onto the controller's state and reaches it over that daemon's unix socket, so the host running the controller is the host that can serve it. Three spellings had to move together for the UI, not one: the `default`, the `defaultText` shown in the options doc, and the description prose that names the old path in words. A grep for the option path finds the first two. The sweep also reached outside nix: `swarm-controller`'s crate README and its `//!` module doc both named the option, as did this repo's own CLAUDE.md and four pages under docs/. An option's name is API, and its documentation lives wherever someone thought to write it down.
166 lines
6.3 KiB
Markdown
166 lines
6.3 KiB
Markdown
# First-run setup (fresh-deploy bootstrap)
|
|
|
|
How to bring a fresh hyperhive hive online: provision accounts, open
|
|
the gateway, bootstrap swarm SSO, make matrix reachable, and spawn the
|
|
first sub-agents.
|
|
|
|
Aimed at `ruth` (the root/manager agent) on a fresh deploy, but it's a
|
|
plain reference doc — read it whenever you need the bootstrap command
|
|
sequence. All `hivectl` commands below run as **root on the host** (not
|
|
inside an agent container); the `request_*` steps run from ruth's own
|
|
turn via the MCP tools.
|
|
|
|
**Bringing up a hive that does not host its own swarm services?** Read
|
|
[`swarm/secrets.md`](swarm/secrets.md) first. Everything below assumes
|
|
each credential is generated where it is read, which is true on an
|
|
all-local deploy and not otherwise — that page says which files an
|
|
operator has to place, and where.
|
|
|
|
## Step-by-step
|
|
|
|
### 1 · Forge
|
|
|
|
```bash
|
|
# Provision (or refresh) ruth's own forge account — do this first. Ruth's
|
|
# bootstrap bypasses the normal spawn-approval flow (see step 6), so unlike
|
|
# every other agent it does not get its forge account auto-provisioned —
|
|
# this manual step is still load-bearing.
|
|
hivectl forge create-user ruth
|
|
|
|
# Sub-agents spawned later (via the approval flow in step 6) get their
|
|
# forge accounts auto-provisioned — nothing to run here for them.
|
|
```
|
|
|
|
The human operator's own forge account is created via swarm SSO instead of
|
|
a manual `hivectl` step — see step 3 (`swarmctl user add`).
|
|
|
|
### 2 · Gateway (HTTP Basic auth)
|
|
|
|
```bash
|
|
# Add an operator login to the gateway (reads password from stdin)
|
|
echo "hunter2" | hivectl gateway create-user mara --password-stdin
|
|
|
|
# List existing users
|
|
hivectl gateway list-users
|
|
```
|
|
|
|
### 3 · Swarm SSO (only when `swarm.authelia.enable`)
|
|
|
|
⚠️ **Required to finish the install, not optional.** Authelia treats an
|
|
empty user store as a fatal startup error, so until this runs the
|
|
container crash-loops and `auth.<swarm.domain>` answers `502 Bad
|
|
Gateway` — a working vhost in front of an upstream that refuses to
|
|
start. Skipping this step looks like a broken proxy.
|
|
|
|
```bash
|
|
# Runs as root on the host that RUNS authelia (not necessarily the
|
|
# controller host). Prints a generated password once — record it.
|
|
swarmctl user add mara --display-name Mara --email mara@example.com --group admins
|
|
```
|
|
|
|
⚠️ **Keep `--group admins`.** It is not decoration: operator-only
|
|
surfaces (the swarm UI below) are gated on that group, and an account
|
|
without it authenticates successfully and is then refused — which reads
|
|
like a broken login rather than a missing group.
|
|
|
|
If an account already exists without it, `user add` will refuse rather
|
|
than amend — adding the group afterwards is `swarmctl user update mara
|
|
--add-group admins`.
|
|
|
|
Detail, including what the password is and why this stays manual:
|
|
[`swarm/sso.md`](swarm/sso.md).
|
|
|
|
### 4 · Swarm UI (only when `deploy.swarm-ui`, on by default with the controller)
|
|
|
|
Nothing to run — it is served on the swarm apex
|
|
(`https://<swarm.domain>/`) as soon as the host rebuilds. Two things
|
|
decide whether you can actually open it:
|
|
|
|
- **You are in `admins`** (step 3). The gateway asks authelia whether
|
|
you have a session; the rule that makes it mean *operator* wants the
|
|
group. Without it you log in and still get bounced.
|
|
- **The name resolves to this host.** It is published to the hive's own
|
|
resolver and to `/etc/hosts` when `gateway.localHostsEntry` is on; from
|
|
anywhere else it needs a real DNS record like any other public name.
|
|
|
|
Detail, including why reachability is deliberately not the access
|
|
control: [`swarm/ui.md`](swarm/ui.md).
|
|
|
|
### 5 · Matrix
|
|
|
|
```bash
|
|
# 5a. Ensure the hive-internal admin account exists first
|
|
hivectl matrix sync-admin
|
|
|
|
# 5b. Provision ruth's own matrix account — same bootstrap-bypass reasoning
|
|
# as forge above, still a required manual step.
|
|
hivectl matrix create-user ruth
|
|
|
|
# 5c. Invite the operator to the hive Space (and optionally to rooms)
|
|
hivectl matrix invite mara
|
|
hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
|
|
|
|
# 5d. Promote the operator to homeserver admin if needed
|
|
hivectl matrix promote-user mara
|
|
```
|
|
|
|
The human operator's own matrix account is created via swarm SSO instead of
|
|
a manual `hivectl` step — see step 3 (`swarmctl user add`).
|
|
|
|
### 6 · Spawn sub-agents
|
|
|
|
Sub-agent creation goes through the approval queue — ruth proposes, the
|
|
operator approves, the container builds. From ruth's own turn (inside
|
|
the container, via MCP tools):
|
|
|
|
```
|
|
# Step 1: initialise a new agent's config repo
|
|
request_init_config(name: "iris")
|
|
# → operator approves → config_ready event lands in the inbox
|
|
|
|
# Step 2: edit /agents/iris/config/agent.nix and commit it. Then the
|
|
# operator spawns iris (dashboard ◆ R3QU3ST SP4WN / Spawn approval),
|
|
# which builds + starts the container from that config.
|
|
|
|
# Later config changes: open a PR on agent-configs/iris (hive-forge);
|
|
# the operator reviews + approves it — no MCP tool call.
|
|
```
|
|
|
|
See [`approvals.md`](approvals.md) for the full flow.
|
|
|
|
### 7 · Useful host commands
|
|
|
|
```bash
|
|
# Roster: all agents, status, rev, parent, pending reminders
|
|
hivectl list-agents
|
|
|
|
# Restart a stuck container (no rebuild)
|
|
hivectl agent <agent> restart
|
|
|
|
# Open a Claude session inside an agent's container
|
|
hivectl agent <agent> choom
|
|
|
|
# Open hive web surfaces in a browser (or just print the URLs)
|
|
hivectl open # operator dashboard
|
|
hivectl open forge # Forgejo
|
|
hivectl open matrix # Matrix GUI (fluffychat)
|
|
```
|
|
|
|
See [`tools/hivectl.md`](tools/hivectl.md) for every `hivectl` verb.
|
|
|
|
## Security notes
|
|
|
|
- **No forge admin token is stored in any agent state dir.** Agents
|
|
hold a regular agent token in their `forge-token` file; sensitive
|
|
creds (the core token, the matrix admin token) live on the host.
|
|
- All config changes (forge PRs on `agent-configs/<name>`) go through
|
|
operator approval — agents can't unilaterally rebuild containers, by design.
|
|
See [`boundary.md`](boundary.md) and [`security.md`](security.md).
|
|
- **Telemetry ingest is authenticated per hive**, and the `hive` label comes
|
|
from which hive authenticated rather than from the payload — so no hive can
|
|
report metrics as another. A first-run all-local hive gets this with nothing
|
|
to configure; joining a swarm you don't host needs one secret copied across.
|
|
See [`observability.md`](observability.md#authenticated-ingest).
|
|
|
|
Once the hive is running, ruth records anything it needs to remember
|
|
across restarts in `/agents/ruth/state/notes.md`.
|