65 lines
3.1 KiB
Markdown
65 lines
3.1 KiB
Markdown
# 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`.
|