First-run setup (fresh-deploy bootstrap)

How to bring a fresh hyperhive hive online: provision accounts, open the gateway, 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.

Step-by-step

1 · Forge

# Provision (or refresh) ruth's own forge account — do this first
hivectl forge create-user ruth

# Create a human operator account (prints the token to stdout)
hivectl forge create-user mara --password hunter2

# Provision forge accounts for any sub-agents spawned later
hivectl forge create-user <agent>

2 · Gateway (HTTP Basic auth)

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

# 3a. Ensure the hive-internal admin account exists first
hivectl matrix sync-admin

# 3b. Provision ruth's own matrix account
hivectl matrix create-user ruth

# 3c. Create a human matrix account
hivectl matrix create-user mara --password hunter2

# 3d. Invite the operator to the hive Space (and optionally to rooms)
hivectl matrix invite mara
hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'

# 3e. Promote the operator to homeserver admin if needed
hivectl matrix promote-user mara

4 · 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 for the full flow.

5 · Useful host commands

# Roster: all agents, status, rev, parent, pending reminders
hivectl agents list

# Restart a stuck container (no rebuild)
hivectl agents restart <agent>

# Open a Claude session inside an agent's container
hivectl choom <agent>

# 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 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 and security.md.

Once the hive is running, ruth records anything it needs to remember across restarts in /agents/ruth/state/notes.md.