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.

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.

GitHub

Write an operator-supplied GitHub personal access token (PAT) into an agent's token file so its gh wrapper + git credential helper can act as the configured bot account. Unlike forge/matrix there is no account creation — the PAT is for an existing GitHub account. The agent must declare hyperhive.githubAccount.

hivectl github set-token damocles --token-stdin   # paste the PAT on stdin (preferred)
hivectl github set-token damocles --token <pat>    # inline (visible in shell history)

• set-token: writes <state>/github-token (0600, agent-owned) via hive-priv — the same credential-injection path as forge/matrix tokens. The gh wrapper / git credential helper read it live, so a freshly-set or rotated PAT takes effect with no rebuild or restart. Refuses an empty token. See github.md for the full flow + security notes.

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 list                # roster: every agent's status + technical state
hivectl agents list --json         # same data as raw JSON rows (for scripting)
hivectl agents restart iris        # stop + start the `iris` container (no rebuild)
hivectl agents restart-all         # stop + start every managed agent container in sequence

list prints a padded table with one row per managed agent — NAME STATUS REV PARENT REMIND. STATUS collapses the health flags (running / stopped, plus needs-login / needs-update when set); REV is the first 12 chars of the agent's locked config sha; PARENT is its place in the topology tree (- for a root agent); REMIND is the count of pending reminders. It reuses the same per-agent aggregation the dashboard renders, so the CLI roster and the web UI never drift. --json emits the raw rows instead of the table.

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 from the agent's state dir. Requires root (same as all machinectl shell operations).

hivectl choom iris                          # fresh blank Claude session in iris's container
hivectl choom iris --resume <session-id>    # rejoin a prior session by id

Bare choom starts a fresh blank session. --resume <value> passes through as claude --resume <value> to rejoin a prior session by its session id — the flag name deliberately matches the claude flag it maps to. (choom never uses claude's --continue: that's a bare flag that takes no argument and resumes the cwd's latest session, i.e. the harness's; a value after it would be consumed as the first prompt, silently poking the live harness session.) A value is required when the flag is given. Either way choom never collides with the harness's live session in the same project dir: the harness pins its own id via --resume, so a blank choom session is invisible to it. 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: the session and CLAUDE.md (the persona) resolve against the right project dir.
• 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, and the role prompt. Each flag is included only when its file exists.
• without the onboarding walkthrough: a boot-time oneshot (hive-claude-onboarding) seeds hasCompletedOnboarding and the project trust flags into ~/.claude.json once before the harness starts, so the first interactive choom lands straight in a session instead of the onboarding/trust dialog the headless harness never completes. It's the single place hyperhive touches that file.

Open

Print (and best-effort open in a browser) one of the hive's web surfaces. Requires the hive-c0re daemon to be running.

hivectl open            # operator dashboard (same as `open home`)
hivectl open home       # operator dashboard (https://<domain>/)
hivectl open forge      # the forge (Forgejo) web UI
hivectl open matrix     # the matrix GUI (fluffychat)

The URL is resolved from the running daemon (HostRequest::Urls), which reads the per-surface public URLs from c0re's service env — so custom forge / matrix domains resolve correctly instead of assuming forge.<domain>. The URL is always printed (the reliable core, since the host is usually headless / driven over SSH), then xdg-open is tried as a convenience — a missing or failing opener is reported as a note, not an error.

A surface has no URL when it isn't browser-reachable: home needs services.hyperhive.domain; forge needs services.hyperhive.forge.behindGateway = true; matrix needs services.hyperhive.matrix.gui.enable = true. In those cases the command exits with a hint naming the option to set.