From da7f1d6c45a943c455ce003bf45c45dd1e327282 Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 15:55:28 +0200 Subject: [PATCH] =?UTF-8?q?docs(tools):=20add=20hivectl.md=20=E2=80=94=20o?= =?UTF-8?q?perator=20host=20CLI=20reference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit hivectl has verbs scattered across CLAUDE.md and domain docs (gateway.md has the gateway subcommands, matrix.md has a brief mention) but no single cheatsheet. Add docs/tools/hivectl.md covering all subcommands: - forge create-user: provision/refresh agent or human forge accounts - matrix create-user / sync-admin / promote-user / reset-password - gateway create-user / delete-user / list-users (htpasswd management) - agents restart / restart-all (container lifecycle via admin socket) - choom [--fresh]: interactive claude session in agent container Also add a reading-path entry to CLAUDE.md pointing at the new file. --- CLAUDE.md | 3 ++ docs/tools/hivectl.md | 109 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 docs/tools/hivectl.md diff --git a/CLAUDE.md b/CLAUDE.md index ff3e1e61..34fe0d8b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -423,6 +423,9 @@ read them à la carte. - **"What verbs does `hive-forge` support? How do I post a comment, upload an attachment, manage subscriptions?"** → [`docs/tools/forge.md`](docs/tools/forge.md). +- **"What does `hivectl` do? How do I provision a forge/matrix account, + manage gateway users, restart containers, or drop into an agent shell?"** → + [`docs/tools/hivectl.md`](docs/tools/hivectl.md). - **"How does the matrix-tuwunel container work? What about fluffychat-web and per-agent matrix accounts?"** → [`docs/matrix.md`](docs/matrix.md). diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md new file mode 100644 index 00000000..644efc9d --- /dev/null +++ b/docs/tools/hivectl.md @@ -0,0 +1,109 @@ +# hivectl + +`hivectl` is the operator-facing host CLI for hyperhive. It lives on the +host (not inside any container) and requires root for most operations. +Available via the `hive-c0re` package in the host NixOS config. + +Unlike the `hive-c0re` daemon subcommands (which go through the broker), +`hivectl` covers direct host-side administration: manual provisioning of +forge + matrix accounts, gateway htpasswd management, container +lifecycle shortcuts, and interactive agent shell access. + +## Forge + +Manual entry to the same idempotent provisioning flow `hive-c0re` runs +at boot. Useful for recovery, ad-hoc re-provisioning, or fixing a single +agent without bouncing the daemon. + +```bash +hivectl forge create-user iris # provision (or refresh) forge account for agent `iris` +hivectl forge create-user mara # create forge account for a human user; prints token to stdout +hivectl forge create-user mara --password hunter2 # set a web-login password +hivectl forge create-user mara --password-stdin # read password from stdin (safer for scripting) +``` + +- For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`): + token is persisted to `/forge-token`. Re-running refreshes the + token (idempotent — scope always matches current `TOKEN_SCOPES`). +- For **non-agents** (humans): creates the account and prints the token to + stdout; no state dir is created. Re-running after account already exists + re-mints the token and prints it again — safe for password resets. +- Without `--password` / `--password-stdin` a random throwaway password + is used (fine for agents — they auth by token). + +## Matrix + +Manual entry to the same idempotent matrix provisioning flow +`hive-c0re` runs at boot. Requires the `hive-matrix` container to be +running (`services.hyperhive.matrix.enable = true`). + +```bash +hivectl matrix create-user iris # provision (or re-provision) matrix account for agent `iris` +hivectl matrix create-user mara # create matrix account for a human; prints access_token to stdout +hivectl matrix create-user mara --password hunter2 # set a client-login password +hivectl matrix sync-admin # provision / refresh the hive internal admin account +hivectl matrix promote-user mara # promote an existing matrix user to homeserver admin +hivectl matrix reset-password iris # generate and set a new random password for `iris`; prints it +``` + +- `create-user`: for agents, persists the `access_token` to + `/matrix-token`. Skips registration when the file already + exists — delete it first to force re-registration. +- `sync-admin`: ensures the hive's internal admin matrix user exists + (used by `hive-c0re` for admin-room commands). Token persisted to the + admin token path. Safe to run again — idempotent. +- `promote-user`: promotes an already-registered user to homeserver + admin via the matrix admin API. Requires `sync-admin` to have run + first (needs a valid admin token). +- `reset-password`: calls the matrix admin API to set a new random + password and prints it to stdout. Useful if an agent or human lost + credentials. + +## Gateway + +Manage users in the gateway's HTTP Basic auth htpasswd file +(`services.hyperhive.gateway.auth`). All commands default to +`/var/lib/hyperhive/gateway/gateway.htpasswd`; pass `--file` to target +a different path. + +```bash +hivectl gateway create-user alice --password-stdin # add (or update) user; read password from stdin +hivectl gateway create-user bob --password hunter2 # add user inline (visible in shell history) +hivectl gateway delete-user bob # remove user +hivectl gateway list-users # list all usernames, one per line +``` + +Passwords are hashed with BCrypt (cost 12). The file is created if it +does not exist. Re-running `create-user` with the same username updates +the password hash in place. + +## Agents + +Container lifecycle shortcuts that go through the host admin socket. +Requires the `hive-c0re` daemon to be running. + +```bash +hivectl agents restart iris # stop + start the `iris` container (no rebuild) +hivectl agents restart-all # stop + start every managed agent container in sequence +``` + +`restart` is the manual equivalent of the MCP `restart` tool — useful +when you need to kick a container from the host without going through +the agent hierarchy. Failures on `restart-all` are collected and +reported at the end rather than aborting mid-run. + +## Choom + +Drop into an interactive Claude session inside an agent container. +Replaces the current process with `machinectl shell h-` running +`claude --continue`. Requires root (same as all `machinectl shell` +operations). + +```bash +hivectl choom iris # join iris's ongoing Claude session (--continue) +hivectl choom iris --fresh # start a new Claude session instead +``` + +Without `--fresh`, `--continue` is passed so the operator joins the +agent's live context window. With `--fresh` a clean session starts. +The container must be running.