hyperhive/docs/tools/hivectl.md

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.

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).

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.

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.

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).

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.