vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(3167): the setup guide gains a swarm UI step, and one group name

Browse source 
Per mara on the PR: the guide someone follows on a fresh deploy is a
different page from the one they read while debugging, and only the
second existed.

Also fixes a contradiction the request surfaced: setup.md and
swarm/sso.md have told every operator to create '--group admins' since
the bootstrap step existed, while the new rule required 'operators'.
This is the first rule that CONSUMES a group name, so it takes the one
the guide already creates - inventing a second would have meant every
account made by following the guide silently failing the check it was
supposed to pass, and for mara specifically a migration step that now
may not be needed at all.

setup.md's step 3 says why --group is not decoration; the new step 4
says what decides whether the page opens (the group, and the name
resolving) rather than listing a command, because there is nothing to
run. Steps renumbered, including the matrix block's internal 4a-4e.
This commit is contained in:
atlas 2026-08-12 17:57:52 +02:00
commit 4dd5093c6f
4 changed files with 51 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/setup.md
View file

@ -49,30 +49,51 @@ start. Skipping this step looks like a broken proxy.
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.
Detail, including what the password is and why this stays manual:
[`swarm/sso.md`](swarm/sso.md).
### 4 · Matrix
### 4 · Swarm UI (only when `swarm.ui.enable`, 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
# 4a. Ensure the hive-internal admin account exists first
# 5a. Ensure the hive-internal admin account exists first
hivectl matrix sync-admin
# 4b. Provision ruth's own matrix account
# 5b. Provision ruth's own matrix account
hivectl matrix create-user ruth
# 4c. Create a human matrix account
# 5c. Create a human matrix account
hivectl matrix create-user mara --password hunter2
# 4d. Invite the operator to the hive Space (and optionally to rooms)
# 5d. Invite the operator to the hive Space (and optionally to rooms)
hivectl matrix invite mara
hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
# 4e. Promote the operator to homeserver admin if needed
# 5e. Promote the operator to homeserver admin if needed
hivectl matrix promote-user mara
```
### 5 · Spawn sub-agents
### 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
@ -93,7 +114,7 @@ request_init_config(name: "iris")
See [`approvals.md`](approvals.md) for the full flow.
### 6 · Useful host commands
### 7 · Useful host commands
```bash
# Roster: all agents, status, rev, parent, pending reminders