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.

This page is the curated guide. For the exhaustive flag-by-flag reference auto-generated from the binary's own command tree, see hivectl-cli.md — emitted by the hidden hivectl markdown-docs subcommand and kept in lockstep with the code by the hivectl-docs flake check (CI fails if the committed copy drifts). Regenerate with nix build .#default && ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md.

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
hivectl matrix invite mara              # invite a user to the hive Space
hivectl matrix invite @mara:server --room '#hive-chat:server'  # ...or to a specific room/alias

• 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.
• invite: invites a matrix user (full @user:server or a bare localpart, qualified with the homeserver's server_name) to the hive Space by default, or to a --room id / #alias. Uses the hive admin token; the admin account must be a member of the target room with invite power (it owns the hive Space, so that case always works). Idempotent — already-member / already-invited is a no-op.

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 <name>@h-<name> running claude --continue from the agent's state dir. 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.

choom reproduces the harness's own claude invocation so the operator lands in a faithful copy of the agent's environment:

• as the agent user, not root: machinectl shell defaults to root, which would make claude read /root/.claude (empty) instead of the agent's /home/<name>/.claude where its OAuth credentials live. choom prefixes the machine with <name>@ (the meta-flake sets the agent's unix user name to its label).
• from /agents/<name>/state: --continue resolves the session for that project dir and CLAUDE.md (the persona) loads from the cwd.
• with the harness flags: --settings, --mcp-config, and --system-prompt-file from /run/hive-config/ — the same files the harness writes each turn — so the operator gets the agent's settings, the hyperhive/matrix MCP tools (which --continue needs to replay a tool-using history), and the role prompt. Each flag is included only when its file exists.