da7f1d6c45
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 <name> [--fresh]: interactive claude session in agent container Also add a reading-path entry to CLAUDE.md pointing at the new file.
109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
# 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 `<state>/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
|
|
`<state>/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-<name>` 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.
|