vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/tools/hivectl-cli.md

30 KiB
Raw Blame History

Command-Line Help for hivectl

This document contains the help content for the hivectl command-line program.

Command Overview:

hivectl

Sibling to the hive-c0re daemon binary. Covers host-side admin operations that don't go through the broker — manual user provisioning on the bundled forge + matrix containers, plus future recovery / debugging verbs.

Usage: hivectl [OPTIONS] <COMMAND>

Subcommands:
  • forge — Forgejo user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (forge::ensure_all) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes without bouncing the daemon
  • matrix — matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (matrix::ensure_all) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register after wiping a token file
  • gateway — Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (services.hyperhive.gateway.auth). Credentials are stored as BCrypt hashes — no extra service or PAM required
  • agents — Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
  • wg — WireGuard inter-hive mesh setup helpers (services.hyperhive.swarm)
  • peer-config — Generate the federation peer-config block for THIS hive — the nix a peer operator pastes into their services.hyperhive.swarm.peers to trust + reach this hive. Emits caCert (+ a cp line for the cert) when this hive serves a self-signed CA, the WireGuard public key when the mesh key exists, and the wireguard{Address,Endpoint} you pass. The hive's own domain is filled in automatically from the running daemon (services.hyperhive.domain). Reads local state (the TLS CA cert, the wg key); never mutates. wg init calls this at the end, so a fresh mesh setup prints the hand-over block too
  • choom — Open an interactive Claude session inside an agent container
  • stop — Stop containers hive-wide in one operator action. Bare hivectl stop stops everything — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: --agents (all sub-agents), --ci / --forge / --gateway / --matrix (named infra), and --agent <name> (repeatable) for specific sub-agents. Flags are additive (e.g. --agents --matrix). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
  • start — Start containers hive-wide — the inverse of hivectl stop. Bare hivectl start starts everything back up; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). Requires the hive-c0re daemon
  • restart — Restart containers hive-wide — stop then start over the same scope. Bare hivectl restart restarts everything (all sub-agents plus the ci/forge/gateway/matrix infra containers); the same scope flags as stop/start narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). If the stop phase reports a failure the start phase is skipped so the operator can investigate. Requires the hive-c0re daemon
  • quota — Per-agent disk accounting + optional quotas via btrfs qgroups
  • subvol — btrfs subvolume management for agent state dirs
  • open — Print (and best-effort open in a browser) a hive web surface URL
  • completions — Generate a shell completion script for hivectl and print it to stdout
Options:

  • --socket <SOCKET> — Path to the hive-c0re host admin socket, used by the daemon-assisted verbs (agents, stop, start). Global: accepted before or after the subcommand. Verbs that don't talk to the daemon ignore it

    Default value: /run/hyperhive/host.sock

hivectl forge

Forgejo user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (forge::ensure_all) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes without bouncing the daemon

Usage: hivectl forge <COMMAND>

Subcommands:
  • create-user — Create or refresh the Forgejo account + token for <name>

hivectl forge create-user

Create or refresh the Forgejo account + token for <name>.

When <name> matches an existing agent (i.e. it has a state dir under /var/lib/hyperhive/agents/), persists the token to <state>/forge-token (idempotent: re-mints + rewrites every call so the on-disk scope matches the current forge::TOKEN_SCOPES).

When <name> is not an agent (a human or any other non-container account), creates the forgejo user and prints the freshly-minted token to stdout — no /var/lib/hyperhive/agents/ directory is created for the user.

Without --password / --password-stdin a random throwaway is used (fine for agents — they auth by token via tea / hive-forge). Set a password to log into the forge web UI afterwards. --password is idempotent: re-running with the same value sets the same password (covers password resets on already-created accounts since forgejo admin user create silently no-ops once the user exists).

Usage: hivectl forge create-user [OPTIONS] <NAME>

Arguments:
  • <NAME> — Forgejo username. For agents: the container/agent name (<n> in h-<n>; manager uses the literal manager). For humans: any forgejo username — mara, damocles, etc
Options:
  • --password <PASSWORD> — Set the account password to this string instead of a random throwaway. Use this for operator accounts that need to log into the forge web UI. Mutually exclusive with --password-stdin. WARNING: the password is visible in shell history + process listings; prefer --password-stdin for anything sensitive
  • --password-stdin — Read the password from stdin (single line, trailing newline stripped) instead of an inline flag. Mutually exclusive with --password

hivectl matrix

matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (matrix::ensure_all) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register after wiping a token file

Usage: hivectl matrix <COMMAND>

Subcommands:
  • create-user — Create or refresh the matrix account + access token for <name>
  • sync-admin — Provision (or re-provision) the hive system admin matrix account (@hive:<server>). hive-c0re runs this automatically on startup before the agent sweep so the account is the first registered user — Conduit/tuwunel grants admin rights to the first user. Run manually to recover a missing admin token file
  • promote-user — Promote a matrix user to homeserver admin via the admin API. Uses the hive system admin token at /var/lib/hyperhive/matrix/admin-token. The server_name is discovered automatically from the running homeserver
  • reset-password — Reset a matrix user's password via the admin API and persist the new password to /var/lib/hyperhive/matrix/creds/<name>-password so the next ensure_user_for (or create-user) can re-login
  • invite — Invite a matrix user to the hive Space (default) or a specific room. Uses the hive admin token; the admin account must be a member of the target room with invite power (it owns the hive Space). Idempotent — already-member / already-invited is a no-op

hivectl matrix create-user

Create or refresh the matrix account + access token for <name>.

When <name> matches an existing agent (i.e. it has a state dir under /var/lib/hyperhive/agents/), persists the token to <state>/matrix-token. Skips registration when the file is already populated; delete it to force re-registration.

When <name> is not an agent (a human or any other non-container account), registers the matrix user and prints the freshly-minted access token to stdout — no /var/lib/hyperhive/agents/ directory is created for the user.

Without --password / --password-stdin a random throwaway is used (fine for agents — they auth by access_token, never by password). Set a password to log into a matrix web client afterwards.

Usage: hivectl matrix create-user [OPTIONS] <NAME>

Arguments:
  • <NAME> — Matrix localpart. For agents: the container/agent name. For humans: any matrix localpart — mara, damocles, etc
Options:
  • --password <PASSWORD> — Set the account password to this string instead of a random throwaway. Use this for operator accounts that need to log into matrix web clients via m.login.password. Mutually exclusive with --password-stdin. WARNING: the password is visible in shell history + process listings; prefer --password-stdin for anything sensitive
  • --password-stdin — Read the password from stdin (single line, trailing newline stripped) instead of an inline flag. Mutually exclusive with --password

hivectl matrix sync-admin

Provision (or re-provision) the hive system admin matrix account (@hive:<server>). hive-c0re runs this automatically on startup before the agent sweep so the account is the first registered user — Conduit/tuwunel grants admin rights to the first user. Run manually to recover a missing admin token file

Usage: hivectl matrix sync-admin

hivectl matrix promote-user

Promote a matrix user to homeserver admin via the admin API. Uses the hive system admin token at /var/lib/hyperhive/matrix/admin-token. The server_name is discovered automatically from the running homeserver

Usage: hivectl matrix promote-user <NAME>

Arguments:
  • <NAME> — Matrix localpart of the user to promote (e.g. argus)

hivectl matrix reset-password

Reset a matrix user's password via the admin API and persist the new password to /var/lib/hyperhive/matrix/creds/<name>-password so the next ensure_user_for (or create-user) can re-login.

After this command succeeds, run hivectl matrix create-user <name> to mint a fresh access token for the agent.

Usage: hivectl matrix reset-password <NAME>

Arguments:
  • <NAME> — Matrix localpart of the account to reset (e.g. argus)

hivectl matrix invite

Invite a matrix user to the hive Space (default) or a specific room. Uses the hive admin token; the admin account must be a member of the target room with invite power (it owns the hive Space). Idempotent — already-member / already-invited is a no-op

Usage: hivectl matrix invite [OPTIONS] <USER>

Arguments:
  • <USER> — User to invite: a full id (@mara:server) or a bare localpart (qualified with the homeserver's server_name)
Options:
  • --room <ROOM> — Target room id (!abc:server) or alias (#name:server). Omit to invite to the hive Space

hivectl gateway

Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (services.hyperhive.gateway.auth). Credentials are stored as BCrypt hashes — no extra service or PAM required

Usage: hivectl gateway <COMMAND>

Subcommands:
  • create-user — Add a new user or update the password of an existing user in the gateway htpasswd file. The password is hashed with BCrypt (cost 12)
  • delete-user — Remove a user from the gateway htpasswd file. Exits with an error when the user is not found so callers can detect the no-op case
  • list-users — List all usernames in the gateway htpasswd file, one per line

hivectl gateway create-user

Add a new user or update the password of an existing user in the gateway htpasswd file. The password is hashed with BCrypt (cost 12).

Pass --password-stdin when scripting or when you don't want the password visible in shell history. The file is created if it does not exist; its parent directory must already exist.

Usage: hivectl gateway create-user [OPTIONS] <USERNAME>

Arguments:
  • <USERNAME> — Username to add or update
Options:

  • --password <PASSWORD> — Set the password inline. WARNING: visible in shell history and process listings — prefer --password-stdin for sensitive input. Mutually exclusive with --password-stdin

  • --password-stdin — Read the password from stdin (single line, trailing newline stripped). Mutually exclusive with --password

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store at /var/lib/hyperhive/gateway/gateway.htpasswd

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

hivectl gateway delete-user

Remove a user from the gateway htpasswd file. Exits with an error when the user is not found so callers can detect the no-op case

Usage: hivectl gateway delete-user [OPTIONS] <USERNAME>

Arguments:
  • <USERNAME> — Username to remove
Options:

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

hivectl gateway list-users

List all usernames in the gateway htpasswd file, one per line

Usage: hivectl gateway list-users [OPTIONS]

Options:

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

hivectl agents

Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)

Usage: hivectl agents <COMMAND>

Subcommands:
  • list — Show all managed agents with their status (running / needs-login / needs-update) and technical state (deployed sha, parent, pending reminders). The host roster overview; reuses the dashboard's per-agent aggregation. Requires the daemon running
  • restart — Stop and start a single agent container without rebuilding config. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config
  • restart-all — Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt

hivectl agents list

Show all managed agents with their status (running / needs-login / needs-update) and technical state (deployed sha, parent, pending reminders). The host roster overview; reuses the dashboard's per-agent aggregation. Requires the daemon running

Usage: hivectl agents list [OPTIONS]

Options:
  • --json — Emit the raw JSON rows instead of the padded table (for scripting). The table is the default human-readable shape

hivectl agents restart

Stop and start a single agent container without rebuilding config. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config

Usage: hivectl agents restart <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, ruth)

hivectl agents restart-all

Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt

Usage: hivectl agents restart-all

hivectl wg

WireGuard inter-hive mesh setup helpers (services.hyperhive.swarm).

One-time-setup convenience so nobody has to remember the wg dance: wg init generates + stores this hive's private key and prints the public key plus the nix snippet to enable the mesh; wg peer prints the snippet to add a remote hive; wg status wraps wg show. The verbs own the imperative state (the key file); the printed nix goes into the operator's host config (kept in git), so nothing here mutates declarative config behind the operator's back.

Usage: hivectl wg <COMMAND>

Subcommands:
  • init — Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives
  • peer — Print the nix snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get <pubkey> from the peer's hivectl wg init
  • status — Show the live mesh interface state (wg show wg-hive). Requires the mesh to be enabled + up

hivectl wg init

Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives

Usage: hivectl wg init [OPTIONS]

Options:
  • --address <ADDRESS> — This hive's mesh address (e.g. 10.42.0.1/32) to bake into the printed snippet. Omit to get a placeholder you fill in

hivectl wg peer

Print the nix snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get <pubkey> from the peer's hivectl wg init

Usage: hivectl wg peer [OPTIONS] --pubkey <PUBKEY> --address <ADDRESS> <DOMAIN>

Arguments:
  • <DOMAIN> — Peer hive's DNS domain (the swarm.peers attrset key)
Options:
  • --pubkey <PUBKEY> — Peer's WireGuard public key (from its hivectl wg init)
  • --address <ADDRESS> — Peer's mesh address (e.g. 10.42.0.2/32)
  • --endpoint <ENDPOINT> — Peer's host:port endpoint (omit for a peer that only dials out, e.g. one behind NAT — it must set an endpoint pointing back here)

hivectl wg status

Show the live mesh interface state (wg show wg-hive). Requires the mesh to be enabled + up

Usage: hivectl wg status

hivectl peer-config

Generate the federation peer-config block for THIS hive — the nix a peer operator pastes into their services.hyperhive.swarm.peers to trust + reach this hive. Emits caCert (+ a cp line for the cert) when this hive serves a self-signed CA, the WireGuard public key when the mesh key exists, and the wireguard{Address,Endpoint} you pass. The hive's own domain is filled in automatically from the running daemon (services.hyperhive.domain). Reads local state (the TLS CA cert, the wg key); never mutates. wg init calls this at the end, so a fresh mesh setup prints the hand-over block too

Usage: hivectl peer-config [OPTIONS]

Options:
  • --wg-address <WG_ADDRESS> — This hive's WireGuard mesh address (e.g. 10.42.0.1/32), emitted as wireguardAddress. Omit when not running the mesh
  • --wg-endpoint <WG_ENDPOINT> — This hive's public WireGuard endpoint (host:port), emitted as wireguardEndpoint. Omit when peers dial in / no mesh

hivectl choom

Open an interactive Claude session inside an agent container.

Runs claude as the agent user from its state dir with the harness's settings / MCP / system prompt. Bare choom <name> is a fresh session; --resume <session-id> rejoins a prior one. Never collides with the harness's live session. Requires root + a running container. See docs/tools/hivectl.md (Choom) for details.

Usage: hivectl choom [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --resume <SESSION> — Resume a prior claude session by its session id, passed through as claude --resume <value> (claude's --continue takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. A value is required when the flag is given

hivectl stop

Stop containers hive-wide in one operator action. Bare hivectl stop stops everything — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: --agents (all sub-agents), --ci / --forge / --gateway / --matrix (named infra), and --agent <name> (repeatable) for specific sub-agents. Flags are additive (e.g. --agents --matrix). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request

Usage: hivectl stop [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)
  • --graceful — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent is enqueued as a GracefulStop on the rebuild queue: the harness is signalled, runs one stop-checkpoint turn to flush durable /state, drains, then the container is stopped (bounded by a 3-min timeout that falls back to a hard stop). Applies to agents only

hivectl start

Start containers hive-wide — the inverse of hivectl stop. Bare hivectl start starts everything back up; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). Requires the hive-c0re daemon

Usage: hivectl start [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)

hivectl restart

Restart containers hive-wide — stop then start over the same scope. Bare hivectl restart restarts everything (all sub-agents plus the ci/forge/gateway/matrix infra containers); the same scope flags as stop/start narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). If the stop phase reports a failure the start phase is skipped so the operator can investigate. Requires the hive-c0re daemon

Usage: hivectl restart [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)
  • --graceful — Gracefully quiesce each agent on the stop half (see stop --graceful). Applies to agents only

hivectl quota

Per-agent disk accounting + optional quotas via btrfs qgroups.

Opt-in: quota enable turns on btrfs qgroup accounting for the agent-state filesystem (a one-time, I/O-heavy rescan — that's why it isn't automatic). Then quota show reports per-agent usage and quota limit caps an agent. No-op on non-btrfs hosts. Operates on agent state subvolumes (created by the btrfs-subvolume migration); agents still on a plain dir report no qgroup usage.

Usage: hivectl quota <COMMAND>

Subcommands:
  • enable — Enable btrfs qgroup accounting on the agent-state filesystem. Run once before show / limit. Triggers a full btrfs rescan (I/O heavy on a large filesystem), so it's a deliberate opt-in. Idempotent; a no-op on non-btrfs hosts
  • show — Report per-agent disk usage (referenced + exclusive bytes) from btrfs qgroups. With no name, shows every agent that has a state subvolume; pass a name to show just that one. Requires enable first
  • limit — Set or clear an agent's disk quota (a referenced-usage cap). size accepts a byte count or a K/M/G/T suffix (e.g. 5G), or none to clear the limit. Requires enable first

hivectl quota enable

Enable btrfs qgroup accounting on the agent-state filesystem. Run once before show / limit. Triggers a full btrfs rescan (I/O heavy on a large filesystem), so it's a deliberate opt-in. Idempotent; a no-op on non-btrfs hosts

Usage: hivectl quota enable

hivectl quota show

Report per-agent disk usage (referenced + exclusive bytes) from btrfs qgroups. With no name, shows every agent that has a state subvolume; pass a name to show just that one. Requires enable first

Usage: hivectl quota show [NAME]

Arguments:
  • <NAME> — Agent to show (omit for all agents with a state subvolume)

hivectl quota limit

Set or clear an agent's disk quota (a referenced-usage cap). size accepts a byte count or a K/M/G/T suffix (e.g. 5G), or none to clear the limit. Requires enable first

Usage: hivectl quota limit <NAME> <SIZE>

Arguments:
  • <NAME> — Agent whose state subvolume to limit
  • <SIZE> — Size cap (5G, 500M, 1073741824) or none to clear

hivectl subvol

btrfs subvolume management for agent state dirs.

New agents get a btrfs subvolume state root automatically (when the host FS is btrfs); agents that predate that are left on plain dirs. subvol upgrade <agent> opts an existing plain-dir agent into the subvolume feature set (snapshots, per-subvol usage/quota, migration) by migrating its state dir in place. Requires the hive-c0re daemon (for the stop/start) and root (for the privileged migration).

Usage: hivectl subvol <COMMAND>

Subcommands:
  • upgrade — Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates …/agents/<name>/ to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires --yes since it bounces the agent and moves its state

hivectl subvol upgrade

Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates …/agents/<name>/ to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires --yes since it bounces the agent and moves its state

Usage: hivectl subvol upgrade [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --yes — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it

hivectl open

Print (and best-effort open in a browser) a hive web surface URL.

Resolves the URL from the running daemon (HostRequest::Urls), so custom forge / matrix domains work without guessing forge.<domain>. Prints the URL unconditionally — the reliable core, since the host is usually headless / driven over SSH where xdg-open is a no-op — then tries xdg-open as a convenience. Bare hivectl open opens the operator dashboard.

Usage: hivectl open [TARGET]

Arguments:

  • <TARGET> — Which surface to open. Defaults to the operator dashboard

    Default value: home

    Possible values:

    • home: The operator dashboard (https://<domain>/)
    • forge: The forge (Forgejo) web UI
    • matrix: The matrix GUI (fluffychat)

hivectl completions

Generate a shell completion script for hivectl and print it to stdout.

Pipe it into your shell's completion path — e.g. for zsh: hivectl completions zsh > ~/.zsh/completions/_hivectl (with that dir on $fpath). The hyperhive NixOS module installs the zsh script system-wide automatically, so this is mainly for ad-hoc / other-shell use. Supports bash, zsh, fish, elvish, and powershell.

Usage: hivectl completions <SHELL>

Arguments:

  • <SHELL> — Shell to emit completions for

    Possible values: bash, elvish, fish, powershell, zsh

This document was generated automatically by clap-markdown.