hyperhive/hivectl

hivectl

The operator-facing host CLI for hyperhive. A thin client for the hive-c0re daemon: it speaks the host admin socket protocol (hive-host-sock) and does not link the daemon crate.

Container lifecycle + the approval queue (agents <spawn|kill|rebuild| restart|…>, approvals <pending|approve|deny>, stop/start) and provisioning (forge/matrix/github/gateway) all forward to the daemon, which owns the broker, the credentials, and the provisioning logic — a running daemon is required for those verbs. A few verbs work off local host state directly instead, so they don't need the socket: wg/peer-config read the mesh key + TLS CA, and choom execs into a container.

When to use it

Reach for this crate when you're adding a new operator-run host command, not an agent-run one — agents talk to the daemon over their own per-agent MCP tool surface (hive-agent-mcp), not this binary. hivectl is what a human operator (or a script on the host) runs.

Shape

One module per subcommand family; main.rs is just the clap parse + top-level dispatch match.

• cli.rs — the clap Cli/Cmd derive tree every other module's Args hangs off of.
• client.rs — the host admin socket client (request), split out so it lives with hivectl rather than in the daemon crate.
• agents.rs — agents <spawn|kill|destroy|rebuild|restart|list| set-parent|…> — container lifecycle.
• approvals.rs — approvals <pending|approve|deny> — the config/ init-config/meta-input approval queue.
• dag_progress.rs — rebuild-queue progress rendering: everything that polls the daemon's DAG queue (HostRequest::QueueDag) and renders per-DAG / per-node progress (spinner or plain), split out because agents.rs was already large.
• power.rs — restart/start/stop at the container level.
• choom.rs — hivectl choom <agent>: drop into an interactive Claude session inside an agent container by exec-ing machinectl shell running claude as the agent user, mirroring the harness's own per-turn claude invocation.
• forge.rs, matrix.rs, github.rs, gateway.rs — per-agent account/token provisioning for each integration (forge create-user, matrix …, github set-token, gateway create-user|delete-user|list-users).
• wg.rs — wg/peer-config: WireGuard mesh helpers — generate this hive's key + the nix snippets to enable the mesh, add a peer, print the block a peer pastes to federate with us, show the live interface.
• subvol.rs — agents subvol: btrfs state-subvolume ops (migrate a plain-dir agent state root to a subvolume, snapshot create/delete/ send).
• quota.rs — resource-quota reporting/enforcement helpers shared across the above.
• open.rs — open <url>: opens a hive URL (dashboard, agent UI) in the operator's browser.
• completions.rs — shell-completion generation (clap_complete/clap-markdown).
• util.rs — small shared helpers (formatting, table rendering) used across subcommand modules.

Full verb reference: docs/tools/hivectl.md.