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

39 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
  • github — GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's github-token state file so its gh wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (hyperhive.github.enable), so no per-agent config is needed
  • 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)
  • approvals — Operator approval queue: list pending requests, approve / deny them. 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 restores the previously-running agents from the last broad-scope stop, or starts everything if no prior stop exists; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). A targeted --agent <name> start is never filtered. 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 github

GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's github-token state file so its gh wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (hyperhive.github.enable), so no per-agent config is needed

Usage: hivectl github <COMMAND>

Subcommands:
  • set-token — Write a GitHub PAT into <agent>'s state dir (github-token, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (hyperhive.github.enable), so the gh wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer --token-stdin: an inline --token is visible in shell history + process listings

hivectl github set-token

Write a GitHub PAT into <agent>'s state dir (github-token, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (hyperhive.github.enable), so the gh wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer --token-stdin: an inline --token is visible in shell history + process listings

Usage: hivectl github set-token [OPTIONS] <AGENT>

Arguments:
  • <AGENT> — Logical agent name (the container/agent name)
Options:
  • --token <TOKEN> — The PAT value inline. Mutually exclusive with --token-stdin
  • --token-stdin — Read the PAT from stdin (trailing newline stripped). Mutually exclusive with --token

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 daemon bcrypt-hashes the password (cost 12) and writes the credential store — hivectl relays over the host socket and never touches the file
  • 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 gateway htpasswd usernames, 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 daemon bcrypt-hashes the password (cost 12) and writes the credential store — hivectl relays over the host socket and never touches the file.

Pass --password-stdin when scripting or when you don't want the password visible in shell history.

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

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 <USERNAME>

Arguments:
  • <USERNAME> — Username to remove

hivectl gateway list-users

List all gateway htpasswd usernames, one per line

Usage: hivectl gateway list-users

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. Rides the job queue (serialized against in-flight rebuilds for the same agent); waits with live progress unless --no-wait
  • restart-all — Restart ALL managed agent containers via one restart DAG each — unrelated agents overlap, each serializes on its own lease. Waits for the whole set with live progress unless --no-wait
  • spawn — Spawn a new agent container directly (h-<name>). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use request-spawn
  • request-spawn — Queue a spawn request as an approval. The container is created on hivectl approvals approve <id> (or the dashboard APPR0VE button)
  • kill — Stop a managed container (graceful)
  • destroy — Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass --purge to also wipe the agent's state dirs (config + creds + notes). No undo
  • rebuild — Apply pending config to a managed container
  • set-parent — Move an agent in the topology tree. Set --parent to a new parent agent name, or pass --root to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents

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. Rides the job queue (serialized against in-flight rebuilds for the same agent); waits with live progress unless --no-wait

Usage: hivectl agents restart [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, ruth)
Options:
  • --no-wait — Return immediately after the restart DAG is queued

hivectl agents restart-all

Restart ALL managed agent containers via one restart DAG each — unrelated agents overlap, each serializes on its own lease. Waits for the whole set with live progress unless --no-wait

Usage: hivectl agents restart-all [OPTIONS]

Options:
  • --no-wait — Return immediately after the restart DAGs are queued

hivectl agents spawn

Spawn a new agent container directly (h-<name>). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use request-spawn

Usage: hivectl agents spawn <NAME>

Arguments:
  • <NAME> — Agent name (e.g. iris)

hivectl agents request-spawn

Queue a spawn request as an approval. The container is created on hivectl approvals approve <id> (or the dashboard APPR0VE button)

Usage: hivectl agents request-spawn <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents kill

Stop a managed container (graceful)

Usage: hivectl agents kill <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents destroy

Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass --purge to also wipe the agent's state dirs (config + creds + notes). No undo

Usage: hivectl agents destroy [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name
Options:
  • --purge

hivectl agents rebuild

Apply pending config to a managed container

Usage: hivectl agents rebuild <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents set-parent

Move an agent in the topology tree. Set --parent to a new parent agent name, or pass --root to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents

Usage: hivectl agents set-parent [OPTIONS] <CHILD>

Arguments:
  • <CHILD> — Agent to move
Options:
  • --parent <PARENT> — New parent agent name. Mutually exclusive with --root
  • --root — Promote child to root (no parent)

hivectl approvals

Operator approval queue: list pending requests, approve / deny them. Requires the hive-c0re daemon to be running (connects to the host admin socket)

Usage: hivectl approvals <COMMAND>

Subcommands:
  • pending — List pending approval requests submitted by agents
  • approve — Approve a pending request by id; the action runs immediately
  • deny — Deny a pending request by id

hivectl approvals pending

List pending approval requests submitted by agents

Usage: hivectl approvals pending

hivectl approvals approve

Approve a pending request by id; the action runs immediately

Usage: hivectl approvals approve <ID>

Arguments:
  • <ID> — Approval id (from hivectl approvals pending)

hivectl approvals deny

Deny a pending request by id

Usage: hivectl approvals deny <ID>

Arguments:
  • <ID> — Approval id

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 gets a graceful-stop DAG on the job 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). All drains overlap. Applies to agents only
  • --no-wait — Return immediately after the stop DAGs are queued instead of waiting for them with live per-node progress

hivectl start

Start containers hive-wide — the inverse of hivectl stop. Bare hivectl start restores the previously-running agents from the last broad-scope stop, or starts everything if no prior stop exists; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). A targeted --agent <name> start is never filtered. 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)
  • --no-wait — Return immediately after the start DAGs are queued instead of waiting for them with live per-node progress

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
  • snapshot — Read-only snapshots of an agent's state subvolume — the first step of the (in-progress) inter-hive migration path, or a manual point-in-time backup

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 subvol snapshot

Read-only snapshots of an agent's state subvolume — the first step of the (in-progress) inter-hive migration path, or a manual point-in-time backup

Usage: hivectl subvol snapshot <COMMAND>

Subcommands:
  • create — Create a read-only snapshot. Agent must already be a subvolume (subvol upgrade first). Prints the snapshot's host path
  • delete — Delete a snapshot created by subvol snapshot create
  • send — Export a snapshot to a local file via btrfs send (the local-file half of inter-hive migration transport; the cross-hive ssh ... btrfs receive leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no --parent produces a self-contained archive of the snapshot

hivectl subvol snapshot create

Create a read-only snapshot. Agent must already be a subvolume (subvol upgrade first). Prints the snapshot's host path

Usage: hivectl subvol snapshot create --label <LABEL> <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --label <LABEL> — Snapshot label. Mandatory, and must start with hive- — the prefix doubles as an allow-list hive-priv checks so only hivectl-issued snapshot names can reach the btrfs subvolume snapshot shellout

hivectl subvol snapshot delete

Delete a snapshot created by subvol snapshot create

Usage: hivectl subvol snapshot delete <NAME> <LABEL>

Arguments:
  • <NAME> — Agent name the snapshot belongs to
  • <LABEL> — Snapshot label passed to subvol snapshot create --label

hivectl subvol snapshot send

Export a snapshot to a local file via btrfs send (the local-file half of inter-hive migration transport; the cross-hive ssh ... btrfs receive leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no --parent produces a self-contained archive of the snapshot

Usage: hivectl subvol snapshot send [OPTIONS] --dest <DEST> <NAME> <LABEL>

Arguments:
  • <NAME> — Agent name the snapshot belongs to
  • <LABEL> — Snapshot label passed to subvol snapshot create --label
Options:
  • --parent <PARENT> — Optional parent snapshot label for an incremental send (btrfs send -p) — must be an existing, older snapshot of the same agent. Omit for a full send
  • --dest <DEST> — Destination filename (not a path) under the migrate-staging dir. Refused if it already exists

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.