Command-Line Help for hivectl

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

Command Overview:

• hivectl↴
• hivectl forge↴
• hivectl forge reconcile-config↴
• hivectl matrix↴
• hivectl matrix invite↴
• hivectl agent↴
• hivectl agent restart↴
• hivectl agent pause↴
• hivectl agent resume↴
• hivectl agent start↴
• hivectl agent stop↴
• hivectl agent kill↴
• hivectl agent destroy↴
• hivectl agent rebuild↴
• hivectl agent choom↴
• hivectl agent watch↴
• hivectl agent quota↴
• hivectl agent quota show↴
• hivectl agent quota set↴
• hivectl agent subvol↴
• hivectl agent subvol upgrade↴
• hivectl agent subvol snapshot↴
• hivectl agent subvol snapshot create↴
• hivectl agent subvol snapshot delete↴
• hivectl agent subvol snapshot send↴
• hivectl agent subvol snapshot push↴
• hivectl list-agents↴
• hivectl quota-enable↴
• hivectl wg↴
• hivectl wg init↴
• hivectl wg peer↴
• hivectl wg status↴
• hivectl peer-config↴
• hivectl stop↴
• hivectl start↴
• hivectl restart↴
• hivectl open↴
• hivectl completions↴

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 matrix container, plus future recovery / debugging verbs.

Usage: hivectl [OPTIONS] <COMMAND>

Subcommands:

• forge — Reconcile an agent's config between this hive and the forge
• matrix — matrix-tuwunel invites
• agent — Lifecycle actions on ONE managed agent container. Needs the hive-c0re daemon running
• list-agents — Show all managed agents with their status and technical state
• quota-enable — Enable btrfs qgroup accounting on the agent-state filesystem
• wg — WireGuard inter-hive mesh setup helpers
• peer-config — Generate the federation peer-config block for THIS hive
• stop — Stop containers hive-wide in one operator action
• start — Start containers hive-wide — the inverse of hivectl stop
• restart — Restart containers hive-wide — stop then start over one scope
• 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 (agent, list-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

Reconcile an agent's config between this hive and the forge.

A human's first SSO login to the forge makes their forge account.

Usage: hivectl forge <COMMAND>

Subcommands:

• reconcile-config — Show + reconcile the divergence between an agent's local applied config checkout and its forge agent-configs/<agent> main

hivectl forge reconcile-config

Show + reconcile the divergence between an agent's local applied config checkout and its forge agent-configs/<agent> main.

Always prints the diff first. --from forge resets the local checkout to forge main (effective on the next deploy); --from local isn't supported yet. With no --from, prompts for the direction.

Usage: hivectl forge reconcile-config [OPTIONS] <AGENT>

Arguments:

• <AGENT> — Agent whose config branches to reconcile

Options:

• --from <FROM> — Which side to reconcile from. Omit it and hivectl prompts you after the diff

  Possible values:

  • forge: Reset the local applied checkout to forge main
  • local: Advance forge main from local — not supported yet

• --verbose — Include the full diff (not just --stat) in the report

hivectl matrix

matrix-tuwunel invites.

Manual invites into the hive Space and its rooms; c0re's periodic matrix sweep provisions the Space, the chat room and the agents' invites on its own.

Usage: hivectl matrix <COMMAND>

Subcommands:

• invite — Invite a matrix user to the hive Space, or a specific room with --room. Idempotent

hivectl matrix invite

Invite a matrix user to the hive Space, or a specific room with --room. Idempotent

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 agent

Lifecycle actions on ONE managed agent container. Needs the hive-c0re daemon running.

Everything here targets a single named agent (hivectl agent foo restart, hivectl agent foo choom, …) — anything that acts hive-wide lives at the top level instead (list-agents, restart/stop/start with a scope, quota-enable).

Usage: hivectl agent <NAME> <COMMAND>

Subcommands:

• restart — Stop and start this agent container without rebuilding config
• pause — Park this agent's turn loop, leaving the container running
• resume — Resume this paused agent — it drains whatever queued up while parked
• start — Start this EXISTING agent container. Fails immediately if name has no config/topology entry at all — it never attempts first-time creation, which is swarm-level (swarmctl agent create)
• stop — Gracefully stop this agent container: signal → drain → reconcile. Never escalates to a hard kill — use kill for that
• kill — Hard-stop this managed container
• destroy — Tear down this sub-agent container, keeping its state by default. No undo
• rebuild — Apply pending config to this managed container
• choom — Open an interactive Claude session inside this agent's container
• watch — Follow this agent's live turn/tool-call event stream from the CLI
• quota — This agent's disk accounting + optional quota via btrfs qgroups
• subvol — btrfs subvolume management for this agent's state dir

Arguments:

• <NAME> — Agent name (for example damocles, iris)

hivectl agent restart

Stop and start this agent container without rebuilding config

Usage: hivectl agent restart [OPTIONS]

Options:

• --no-wait — Return immediately after hivectl queues the restart DAG

hivectl agent pause

Park this agent's turn loop, leaving the container running.

The harness stops driving turns but keeps serving its web UI and MCP daemons, so the container, its mounts and its warm caches stay up while it burns no tokens. Inbox messages queue unacked and the backlog drains on resume. Sticky: it survives a restart, and pausing a stopped agent makes it come up paused.

Usage: hivectl agent pause [OPTIONS]

Options:

• --no-wait — Return immediately after hivectl queues the pause DAG instead of waiting for the harness to acknowledge it

hivectl agent resume

Resume this paused agent — it drains whatever queued up while parked

Usage: hivectl agent resume

hivectl agent start

Start this EXISTING agent container. Fails immediately if name has no config/topology entry at all — it never attempts first-time creation, which is swarm-level (swarmctl agent create)

Usage: hivectl agent start [OPTIONS]

Options:

• --paused — Start (or leave) the agent paused: if it's currently down, hivectl writes the pause marker before the container boots, so it comes up paused instead of driving turns immediately. If it's already running, this pauses it in place and doesn't attempt a (re)start

hivectl agent stop

Gracefully stop this agent container: signal → drain → reconcile. Never escalates to a hard kill — use kill for that

Usage: hivectl agent stop

hivectl agent kill

Hard-stop this managed container

Usage: hivectl agent kill

hivectl agent destroy

Tear down this sub-agent container, keeping its state by default. No undo

Usage: hivectl agent destroy [OPTIONS]

Options:

• --purge — Also wipe the agent's state dirs (config + creds + notes)

hivectl agent rebuild

Apply pending config to this managed container

Usage: hivectl agent rebuild

hivectl agent choom

Open an interactive Claude session inside this agent's container.

A fresh session by default, or resume a prior one. Requires root or hive-admin group membership, plus a running container.

Usage: hivectl agent choom [OPTIONS]

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. Requires a value

hivectl agent watch

Follow this agent's live turn/tool-call event stream from the CLI.

Prints one compact line per event as they happen. Ctrl-C to stop. Requires the agent to be running.

Usage: hivectl agent watch

hivectl agent quota

This agent's disk accounting + optional quota via btrfs qgroups.

Needs hivectl quota-enable run once hive-wide first. No-op on non-btrfs hosts.

Usage: hivectl agent quota <COMMAND>

Subcommands:

• show — Report this agent's disk usage from btrfs qgroups
• set — Set or clear this agent's disk-usage quota

hivectl agent quota show

Report this agent's disk usage from btrfs qgroups

Usage: hivectl agent quota show

hivectl agent quota set

Set or clear this agent's disk-usage quota

Usage: hivectl agent quota set <SIZE>

Arguments:

• <SIZE> — Size cap (5G, 500M, 1073741824) or none to clear

hivectl agent subvol

btrfs subvolume management for this agent's state dir.

Upgrade an existing plain-dir agent's state into a btrfs subvolume so it gains snapshots and per-subvol usage/quota.

Usage: hivectl agent subvol <COMMAND>

Subcommands:

• upgrade — Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota
• snapshot — Read-only snapshots of this agent's state subvolume

hivectl agent subvol upgrade

Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota.

Bounces the agent to migrate its state, so it requires --yes.

Usage: hivectl agent subvol upgrade [OPTIONS]

Options:

• --yes — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it

hivectl agent subvol snapshot

Read-only snapshots of this agent's state subvolume

Usage: hivectl agent subvol snapshot <COMMAND>

Subcommands:

• create — Create a read-only snapshot (agent must already be a subvolume)
• 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 the inter-hive migration transport (push is the network half). Also useful standalone as a point-in-time backup: a full send with no --parent produces a self-contained archive of the snapshot
• push — Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport

hivectl agent subvol snapshot create

Create a read-only snapshot (agent must already be a subvolume)

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

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

Delete a snapshot created by subvol snapshot create

Usage: hivectl agent subvol snapshot delete <LABEL>

Arguments:

• <LABEL> — Snapshot label passed to subvol snapshot create --label

hivectl agent subvol snapshot send

Export a snapshot to a local file via btrfs send — the local-file half of the inter-hive migration transport (push is the network half). 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 agent subvol snapshot send [OPTIONS] --dest <DEST> <LABEL>

Arguments:

• <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 agent subvol snapshot push

Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport.

Stages nothing locally: btrfs send writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here.

No destination argument exists: a swarm has one store, read from services.hyperhive.swarm.snapshotStore.

Usage: hivectl agent subvol snapshot push [OPTIONS] <LABEL>

Arguments:

• <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, and must already be present on the receiver. Omit for a full send

hivectl list-agents

Show all managed agents with their status and technical state.

Global — not scoped to one agent, so it lives at the top level rather than under hivectl agent <name>. Needs the hive-c0re daemon running.

Usage: hivectl list-agents [OPTIONS]

Options:

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

hivectl quota-enable

Enable btrfs qgroup accounting on the agent-state filesystem.

Global one-shot toggle (not per-agent), hence top-level rather than under hivectl agent <name>. Idempotent — safe to re-run. Once enabled, hivectl agent <name> quota show/quota set work.

Usage: hivectl quota-enable

hivectl wg

WireGuard inter-hive mesh setup helpers.

Generate this hive's mesh key and print the nix to enable the mesh, add a peer, or inspect live interface state.

Usage: hivectl wg <COMMAND>

Subcommands:

• init — Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh
• peer — Print the nix to add a peer hive to the mesh
• status — Show the live mesh interface state

hivectl wg init

Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh

Usage: hivectl wg init [OPTIONS]

Options:

• --address <ADDRESS> — This hive's mesh address (for example 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 to add a peer hive to the mesh

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

Arguments:

• <DOMAIN> — Peer hive's DNS domain (its swarm.hives entry's domain)

Options:

• --pubkey <PUBKEY> — Peer's WireGuard public key (from its hivectl wg init)
• --address <ADDRESS> — Peer's mesh address (for example 10.42.0.2/32)
• --endpoint <ENDPOINT> — Peer's host:port endpoint (omit for a peer that only dials out, for example one behind NAT — it must set an endpoint pointing back here)

hivectl wg status

Show the live mesh interface state

Usage: hivectl wg status

hivectl peer-config

Generate the federation peer-config block for THIS hive.

Prints the nix a peer operator pastes into their swarm config to trust and reach this hive.

Usage: hivectl peer-config [OPTIONS]

Options:

• --wg-address <WG_ADDRESS> — This hive's WireGuard mesh address (for example 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 stop

Stop containers hive-wide in one operator action.

Bare hivectl stop stops every agent and the gateway; scope flags narrow it to specific sub-agents or the gateway. The swarm's forge and matrix are never in scope: systemd on the services host runs them.

Usage: hivectl stop [OPTIONS]

Options:

• --agents — All sub-agent containers
• --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
• --gateway — The gateway (hive-gateway) — nginx on the host, not a container
• --graceful — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent gets a graceful-stop DAG on the job queue: it signals the harness, which runs one stop-checkpoint turn to flush durable /state and drains, then the DAG stops the container (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 hivectl queues the stop DAGs 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 agents stopped by the last broad-scope stop (or starts everything if none); scope flags narrow it. The swarm's forge and matrix are never in scope.

Usage: hivectl start [OPTIONS]

Options:

• --agents — All sub-agent containers
• --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
• --gateway — The gateway (hive-gateway) — nginx on the host, not a container
• --no-wait — Return immediately after hivectl queues the start DAGs instead of waiting for them with live per-node progress

hivectl restart

Restart containers hive-wide — stop then start over one scope.

Bare hivectl restart restarts everything; scope flags narrow it. The swarm's forge and matrix are never in scope.

Usage: hivectl restart [OPTIONS]

Options:

• --agents — All sub-agent containers
• --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
• --gateway — The gateway (hive-gateway) — nginx on the host, not a container
• --graceful — Gracefully quiesce each agent on the stop half (see stop --graceful). Applies to agents only

hivectl open

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

Resolves the URL from the running daemon so custom forge / matrix domains work. 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://<hive>.hives.<swarm 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.

Supports bash, zsh, fish, elvish, and powershell. The NixOS module already installs the zsh script system-wide; this is for ad-hoc or other-shell use.

Usage: hivectl completions <SHELL>

Arguments:

• <SHELL> — Shell to emit completions for

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