vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

hivectl: rename hivectl agents to hivectl agent <name> <verb>

Browse source
This commit is contained in:
damocles 2026-07-27 19:00:44 +02:00 • committed by mara
commit 03afbd1316
19 changed files with 367 additions and 525 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/agent-hierarchy.md
View file

@ -26,7 +26,7 @@ above was spawned by `alice`), and the operator can reparent any agent. The
bootstrap container (`ruth`) is just another root. Re-parenting is
operator-driven:
- CLI: `hivectl agents set-parent <child> --parent <new>` (or `--root` to
- CLI: `hivectl agent <child> set-parent --parent <new>` (or `--root` to
promote). Exactly one of `--parent` / `--root` is required.
- Dashboard: `POST /api/topology/set-parent` (form fields `child`,
optional `new_parent` — absent / empty ⇒ promote to root).

2
docs/approvals.md
View file

@ -119,7 +119,7 @@ kind-specific payload carrier.
- `Spawn` — direct container creation from the agent's config repo.
`commit_ref` is empty. Submitted via `HostRequest::RequestSpawn`
(operator-gated, the `◆ R3QU3ST SP4WN` dashboard button +
`hivectl agents request-spawn` CLI). The host-level `HostRequest::Spawn`
`hivectl agent <name> request-spawn` CLI). The host-level `HostRequest::Spawn`
variant bypasses the approval queue entirely — privileged-context use
only (operator on the host shell, test scripts, one-off recoveries).
This is the **canonical first-spawn**: a new agent's `InitConfig`

4
docs/persistence.md
View file

@ -212,7 +212,7 @@ bind-mount, and that's the whole design: the harness stats it
in-container via `hive_sh4re::paths::paused_marker`, while hive-c0re
stats it on the host (`Coordinator::is_paused`) to populate the
`paused` field on the agent card, and creates/removes it
(`Coordinator::set_paused`) for `hivectl agents pause|resume` and the
(`Coordinator::set_paused`) for `hivectl agent <name> pause|resume` and the
dashboard toggle. Because the file itself is the only shared state
there's no protocol between them, no round-trip into the container, and
pause keeps working when the harness is wedged or the container is
@ -339,7 +339,7 @@ step would re-fire).
`R3V1V3` queues a Spawn approval that reuses the kept state on
approve (no re-login).
- `PURG3` (opt-in via the dashboard button or
`hivectl agents destroy --purge <name>`) — DESTR0Y plus wipes
`hivectl agent <name> destroy --purge`) — DESTR0Y plus wipes
`/var/lib/hyperhive/{agents,applied}/<name>/`. Config history,
claude creds, /state/ notes, and the harness dir are all gone.
No undo.

6
docs/setup.md
View file

@ -79,13 +79,13 @@ See [`approvals.md`](approvals.md) for the full flow.
```bash
# Roster: all agents, status, rev, parent, pending reminders
hivectl agents list
hivectl list-agents
# Restart a stuck container (no rebuild)
hivectl agents restart <agent>
hivectl agent <agent> restart
# Open a Claude session inside an agent's container
hivectl choom <agent>
hivectl agent <agent> choom
# Open hive web surfaces in a browser (or just print the URLs)
hivectl open # operator dashboard

359
docs/tools/hivectl-cli.md
View file

@ -20,29 +20,29 @@ This document contains the help content for the `hivectl` command-line program.
* [`hivectl gateway create-user`↴](#hivectl-gateway-create-user)
* [`hivectl gateway delete-user`↴](#hivectl-gateway-delete-user)
* [`hivectl gateway list-users`↴](#hivectl-gateway-list-users)
* [`hivectl agents`↴](#hivectl-agents)
* [`hivectl agents list`↴](#hivectl-agents-list)
* [`hivectl agents restart`↴](#hivectl-agents-restart)
* [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
* [`hivectl agents pause`↴](#hivectl-agents-pause)
* [`hivectl agents resume`↴](#hivectl-agents-resume)
* [`hivectl agents spawn`↴](#hivectl-agents-spawn)
* [`hivectl agents request-spawn`↴](#hivectl-agents-request-spawn)
* [`hivectl agents kill`↴](#hivectl-agents-kill)
* [`hivectl agents destroy`↴](#hivectl-agents-destroy)
* [`hivectl agents rebuild`↴](#hivectl-agents-rebuild)
* [`hivectl agents set-parent`↴](#hivectl-agents-set-parent)
* [`hivectl agents set-limits`↴](#hivectl-agents-set-limits)
* [`hivectl agents quota`↴](#hivectl-agents-quota)
* [`hivectl agents quota enable`↴](#hivectl-agents-quota-enable)
* [`hivectl agents quota show`↴](#hivectl-agents-quota-show)
* [`hivectl agents quota set`↴](#hivectl-agents-quota-set)
* [`hivectl agents subvol`↴](#hivectl-agents-subvol)
* [`hivectl agents subvol upgrade`↴](#hivectl-agents-subvol-upgrade)
* [`hivectl agents subvol snapshot`↴](#hivectl-agents-subvol-snapshot)
* [`hivectl agents subvol snapshot create`↴](#hivectl-agents-subvol-snapshot-create)
* [`hivectl agents subvol snapshot delete`↴](#hivectl-agents-subvol-snapshot-delete)
* [`hivectl agents subvol snapshot send`↴](#hivectl-agents-subvol-snapshot-send)
* [`hivectl agent`↴](#hivectl-agent)
* [`hivectl agent restart`↴](#hivectl-agent-restart)
* [`hivectl agent pause`↴](#hivectl-agent-pause)
* [`hivectl agent resume`↴](#hivectl-agent-resume)
* [`hivectl agent spawn`↴](#hivectl-agent-spawn)
* [`hivectl agent request-spawn`↴](#hivectl-agent-request-spawn)
* [`hivectl agent kill`↴](#hivectl-agent-kill)
* [`hivectl agent destroy`↴](#hivectl-agent-destroy)
* [`hivectl agent rebuild`↴](#hivectl-agent-rebuild)
* [`hivectl agent set-parent`↴](#hivectl-agent-set-parent)
* [`hivectl agent set-limits`↴](#hivectl-agent-set-limits)
* [`hivectl agent choom`↴](#hivectl-agent-choom)
* [`hivectl agent quota`↴](#hivectl-agent-quota)
* [`hivectl agent quota show`↴](#hivectl-agent-quota-show)
* [`hivectl agent quota set`↴](#hivectl-agent-quota-set)
* [`hivectl agent subvol`↴](#hivectl-agent-subvol)
* [`hivectl agent subvol upgrade`↴](#hivectl-agent-subvol-upgrade)
* [`hivectl agent subvol snapshot`↴](#hivectl-agent-subvol-snapshot)
* [`hivectl agent subvol snapshot create`↴](#hivectl-agent-subvol-snapshot-create)
* [`hivectl agent subvol snapshot delete`↴](#hivectl-agent-subvol-snapshot-delete)
* [`hivectl agent subvol snapshot send`↴](#hivectl-agent-subvol-snapshot-send)
* [`hivectl list-agents`↴](#hivectl-list-agents)
* [`hivectl quota-enable`↴](#hivectl-quota-enable)
* [`hivectl approvals`↴](#hivectl-approvals)
* [`hivectl approvals pending`↴](#hivectl-approvals-pending)
* [`hivectl approvals approve`↴](#hivectl-approvals-approve)
@ -52,7 +52,6 @@ This document contains the help content for the `hivectl` command-line program.
* [`hivectl wg peer`↴](#hivectl-wg-peer)
* [`hivectl wg status`↴](#hivectl-wg-status)
* [`hivectl peer-config`↴](#hivectl-peer-config)
* [`hivectl choom`↴](#hivectl-choom)
* [`hivectl stop`↴](#hivectl-stop)
* [`hivectl start`↴](#hivectl-start)
* [`hivectl restart`↴](#hivectl-restart)
@ -71,11 +70,12 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
* `matrix` — matrix-tuwunel user provisioning
* `github` — GitHub account provisioning
* `gateway` — Gateway htpasswd user management
* `agents` — Agent container management
* `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
* `approvals` — Operator approval queue: list, approve, or deny pending requests
* `wg` — WireGuard inter-hive mesh setup helpers
* `peer-config` — Generate the federation peer-config block for THIS hive
* `choom` — Open an interactive Claude session inside an agent container
* `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
@ -84,7 +84,7 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
###### **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
* `--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`
@ -327,54 +327,41 @@ List all gateway htpasswd usernames, one per line
## `hivectl agents`
## `hivectl agent`
Agent container management.
Lifecycle actions on ONE managed agent container. Needs the hive-c0re daemon running.
Lifecycle actions on managed agent containers. 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 agents <COMMAND>`
**Usage:** `hivectl agent <NAME> <COMMAND>`
###### **Subcommands:**
* `list` — Show all managed agents with their status and technical state
* `restart` — Stop and start a single agent container without rebuilding config
* `restart-all` — Restart all managed agent containers
* `pause` — Park an agent's turn loop, leaving the container running
* `resume` — Resume a paused agent — it drains whatever queued up while parked
* `spawn` — Spawn a new agent container directly, bypassing the approval queue
* `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
* `spawn` — Spawn this agent container directly, bypassing the approval queue
* `request-spawn` — Queue a spawn request for operator approval
* `kill` — Stop a managed container (graceful)
* `destroy` — Tear down a sub-agent container, keeping its state by default. No undo
* `rebuild` — Apply pending config to a managed container
* `set-parent` — Move an agent in the topology tree — under a new parent, or to root
* `set-limits` — Declare an agent's CPU/memory limits, overriding the hive-wide defaults
* `quota` — Per-agent disk accounting + optional quotas via btrfs qgroups
* `subvol` — btrfs subvolume management for agent state dirs
## `hivectl agents list`
Show all managed agents with their status and technical state
**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
**Usage:** `hivectl agents restart [OPTIONS] <NAME>`
* `kill` — Stop this managed container (graceful)
* `destroy` — Tear down this sub-agent container, keeping its state by default. No undo
* `rebuild` — Apply pending config to this managed container
* `set-parent` — Move this agent in the topology tree — under a new parent, or to root
* `set-limits` — Declare this agent's CPU/memory limits, overriding the hive-wide defaults
* `choom` — Open an interactive Claude session inside this agent's container
* `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 (e.g. `damocles`, `ruth`)
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
## `hivectl agent restart`
Stop and start this agent container without rebuilding config
**Usage:** `hivectl agent restart [OPTIONS]`
###### **Options:**
@ -382,91 +369,55 @@ Stop and start a single agent container without rebuilding config
## `hivectl agents restart-all`
## `hivectl agent pause`
Restart all managed agent containers
**Usage:** `hivectl agents restart-all [OPTIONS]`
###### **Options:**
* `--no-wait` — Return immediately after the restart DAGs are queued
## `hivectl agents pause`
Park an agent's turn loop, leaving the container running.
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 agents pause <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent pause`
## `hivectl agents resume`
## `hivectl agent resume`
Resume a paused agent — it drains whatever queued up while parked
Resume this paused agent — it drains whatever queued up while parked
**Usage:** `hivectl agents resume <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent resume`
## `hivectl agents spawn`
## `hivectl agent spawn`
Spawn a new agent container directly, bypassing the approval queue.
Spawn this agent container directly, bypassing the approval queue.
Operator-on-the-host only; use `request-spawn` for an approval-gated spawn.
**Usage:** `hivectl agents spawn <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name (e.g. `iris`)
**Usage:** `hivectl agent spawn`
## `hivectl agents request-spawn`
## `hivectl agent request-spawn`
Queue a spawn request for operator approval
**Usage:** `hivectl agents request-spawn <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent request-spawn`
## `hivectl agents kill`
## `hivectl agent kill`
Stop a managed container (graceful)
Stop this managed container (graceful)
**Usage:** `hivectl agents kill <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent kill`
## `hivectl agents destroy`
## `hivectl agent destroy`
Tear down a sub-agent container, keeping its state by default. No undo
Tear down this sub-agent container, keeping its state by default. No undo
**Usage:** `hivectl agents destroy [OPTIONS] <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent destroy [OPTIONS]`
###### **Options:**
@ -474,46 +425,34 @@ Tear down a sub-agent container, keeping its state by default. No undo
## `hivectl agents rebuild`
## `hivectl agent rebuild`
Apply pending config to a managed container
Apply pending config to this managed container
**Usage:** `hivectl agents rebuild <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent rebuild`
## `hivectl agents set-parent`
## `hivectl agent set-parent`
Move an agent in the topology tree — under a new parent, or to root
Move this agent in the topology tree — under a new parent, or to root
**Usage:** `hivectl agents set-parent [OPTIONS] <CHILD>`
###### **Arguments:**
* `<CHILD>` — Agent to move
**Usage:** `hivectl agent set-parent [OPTIONS]`
###### **Options:**
* `--parent <PARENT>` — New parent agent name. Mutually exclusive with `--root`
* `--root` — Promote `child` to root (no parent)
* `--root` — Promote this agent to root (no parent)
## `hivectl agents set-limits`
## `hivectl agent set-limits`
Declare an agent's CPU/memory limits, overriding the hive-wide defaults.
Declare this agent's CPU/memory limits, overriding the hive-wide defaults.
Replaces the agent's whole override entry rather than merging into it: any limit you don't pass returns to the hive-wide default. To change one and keep the other, pass both. Disk is a separate resource with its own group — see `agents quota`.
Replaces the agent's whole override entry rather than merging into it: any limit you don't pass returns to the hive-wide default. To change one and keep the other, pass both. Disk is a separate resource with its own group — see `quota`.
**Usage:** `hivectl agents set-limits [OPTIONS] <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name
**Usage:** `hivectl agent set-limits [OPTIONS]`
###### **Options:**
@ -523,85 +462,77 @@ Replaces the agent's whole override entry rather than merging into it: any limit
## `hivectl agents quota`
## `hivectl agent choom`
Per-agent disk accounting + optional quotas via btrfs qgroups.
Open an interactive Claude session inside this agent's container.
Opt-in: enable qgroup accounting, then report per-agent usage or cap an agent. No-op on non-btrfs hosts.
A fresh session by default, or resume a prior one. Requires root and a running container.
**Usage:** `hivectl agents quota <COMMAND>`
**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. A value is required when the flag is given
## `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:**
* `enable` — Enable btrfs qgroup accounting on the agent-state filesystem
* `show` — Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
* `set` — Set or clear an agent's disk-usage quota
* `show` — Report this agent's disk usage from btrfs qgroups
* `set` — Set or clear this agent's disk-usage quota
## `hivectl agents quota enable`
## `hivectl agent quota show`
Enable btrfs qgroup accounting on the agent-state filesystem.
Report this agent's disk usage from btrfs qgroups
Run once before `show` / `limit`. No-op on non-btrfs hosts.
**Usage:** `hivectl agents quota enable`
**Usage:** `hivectl agent quota show`
## `hivectl agents quota show`
## `hivectl agent quota set`
Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
Set or clear this agent's disk-usage quota
**Usage:** `hivectl agents quota show [NAME]`
**Usage:** `hivectl agent quota set <SIZE>`
###### **Arguments:**
* `<NAME>` — Agent to show (omit for all agents with a state subvolume)
## `hivectl agents quota set`
Set or clear an agent's disk-usage quota.
Named `set` rather than `set-quota` because the enclosing `quota` group already carries the noun — `agents quota set iris 5G`. The `set-<noun>` spelling stays for the flat verbs (`set-parent`, `set-limits`), which have no group to inherit it from.
**Usage:** `hivectl agents quota set <NAME> <SIZE>`
###### **Arguments:**
* `<NAME>` — Agent whose state subvolume to limit
* `<SIZE>` — Size cap (`5G`, `500M`, `1073741824`) or `none` to clear
## `hivectl agents subvol`
## `hivectl agent subvol`
btrfs subvolume management for agent state dirs.
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 agents subvol <COMMAND>`
**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 an agent's state subvolume
* `snapshot` — Read-only snapshots of this agent's state subvolume
## `hivectl agents subvol upgrade`
## `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 agents subvol upgrade [OPTIONS] <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
**Usage:** `hivectl agent subvol upgrade [OPTIONS]`
###### **Options:**
@ -609,11 +540,11 @@ Bounces the agent to migrate its state, so it requires `--yes`.
## `hivectl agents subvol snapshot`
## `hivectl agent subvol snapshot`
Read-only snapshots of an agent's state subvolume
Read-only snapshots of this agent's state subvolume
**Usage:** `hivectl agents subvol snapshot <COMMAND>`
**Usage:** `hivectl agent subvol snapshot <COMMAND>`
###### **Subcommands:**
@ -623,15 +554,11 @@ Read-only snapshots of an agent's state subvolume
## `hivectl agents subvol snapshot create`
## `hivectl agent subvol snapshot create`
Create a read-only snapshot (agent must already be a subvolume)
**Usage:** `hivectl agents subvol snapshot create --label <LABEL> <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
**Usage:** `hivectl agent subvol snapshot create --label <LABEL>`
###### **Options:**
@ -639,28 +566,26 @@ Create a read-only snapshot (agent must already be a subvolume)
## `hivectl agents subvol snapshot delete`
## `hivectl agent subvol snapshot delete`
Delete a snapshot created by `subvol snapshot create`
**Usage:** `hivectl agents subvol snapshot delete <NAME> <LABEL>`
**Usage:** `hivectl agent subvol snapshot delete <LABEL>`
###### **Arguments:**
* `<NAME>` — Agent name the snapshot belongs to
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
## `hivectl agents subvol snapshot send`
## `hivectl agent 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 agents subvol snapshot send [OPTIONS] --dest <DEST> <NAME> <LABEL>`
**Usage:** `hivectl agent subvol snapshot send [OPTIONS] --dest <DEST> <LABEL>`
###### **Arguments:**
* `<NAME>` — Agent name the snapshot belongs to
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
###### **Options:**
@ -670,6 +595,30 @@ Export a snapshot to a local file via `btrfs send` (the local-file half of inter
## `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 approvals`
Operator approval queue: list, approve, or deny pending requests.
@ -787,24 +736,6 @@ Prints the nix a peer operator pastes into their swarm config to trust and reach
## `hivectl choom`
Open an interactive Claude session inside an agent container.
A fresh session by default, or resume a prior one. Requires root and a running container.
**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.

40
docs/tools/hivectl.md
View file

@ -132,18 +132,19 @@ username updates the password hash in place.
## Agents
Container lifecycle shortcuts that go through the host admin socket.
Requires the `hive-c0re` daemon to be running.
Requires the `hive-c0re` daemon to be running. Everything scoped to a
single agent lives under `hivectl agent <name> <verb>` — the name is
hoisted onto the parent command, so none of the verbs below repeat it.
```bash
hivectl agents list # roster: every agent's status + technical state
hivectl agents list --json # same data as raw JSON rows (for scripting)
hivectl agents restart iris # stop + start the `iris` container (no rebuild)
hivectl agents restart-all # stop + start every managed agent container in sequence
hivectl agents pause iris # park iris's turn loop, leave the container running
hivectl agents resume iris # let it drive turns again, draining what queued up
hivectl list-agents # roster: every agent's status + technical state
hivectl list-agents --json # same data as raw JSON rows (for scripting)
hivectl agent iris restart # stop + start the `iris` container (no rebuild)
hivectl agent iris pause # park iris's turn loop, leave the container running
hivectl agent iris resume # let it drive turns again, draining what queued up
```
`list` prints a padded table with one row per managed agent —
`list-agents` prints a padded table with one row per managed agent —
`NAME STATUS REV PARENT REMIND`. STATUS collapses the health flags
(`running` / `stopped`, plus ` paused` / ` needs-login` / ` needs-update`
when set — `paused` is orthogonal to running, see below);
@ -153,10 +154,13 @@ pending reminders. It reuses the same per-agent aggregation the dashboard
renders, so the CLI roster and the web UI never drift. `--json` emits the
raw rows instead of the table.
`restart` is the manual equivalent of the MCP `restart` tool — useful
when you need to kick a container from the host without going through
the agent hierarchy. Failures on `restart-all` are collected and
reported at the end rather than aborting mid-run.
`agent <name> restart` is the manual equivalent of the MCP `restart`
tool — useful when you need to kick a container from the host without
going through the agent hierarchy. For more than one agent at once, use
the top-level `hivectl restart --agents` (or `--agent <name>` repeated) —
it rides a single DAG and reports per-target failures at the end rather
than aborting mid-run, instead of shelling out to `agent <name> restart`
in a loop.
`pause` / `resume` are the "stop burning tokens without losing the
container" pair. Pausing writes a marker file into the agent's harness
@ -175,15 +179,15 @@ resume drains the backlog rather than dropping it. Points worth knowing:
handshake is skipped for a paused agent (it would never answer), which
is safe precisely because the pause check sits at the top of the loop:
a paused agent has no turn in flight to checkpoint.
- Visible as ` paused` in `agents list`'s STATUS column, as a `paused`
- Visible as ` paused` in `list-agents`'s STATUS column, as a `paused`
field on the JSON rows, and as a badge on the dashboard card.
### Per-agent resource limits
```bash
hivectl agents set-limits sock --cpu-quota 400% --memory-max 8G
hivectl agents set-limits sock --memory-max 8G # CPU falls back to the hive default
hivectl agents set-limits sock --reset # drop all overrides
hivectl agent sock set-limits --cpu-quota 400% --memory-max 8G
hivectl agent sock set-limits --memory-max 8G # CPU falls back to the hive default
hivectl agent sock set-limits --reset # drop all overrides
```
Overrides the hive-wide `services.hyperhive.agentCpuQuota` /
@ -224,8 +228,8 @@ tells you it needs root, instead of reporting a permission problem with
the state dir.
```bash
hivectl choom iris # fresh blank Claude session in iris's container
hivectl choom iris --resume <session-id> # rejoin a prior session by id
hivectl agent iris choom # fresh blank Claude session in iris's container
hivectl agent iris choom --resume <session-id> # rejoin a prior session by id
```
Bare `choom` starts a fresh blank session. `--resume <value>` passes

2
docs/turn-loop.md
View file

@ -15,7 +15,7 @@ agents) runs:
losing it; reminders and todo wakes buffer in their channels. The
check runs before the self-continue slot is consumed, so a pending
`request_next_turn` survives the pause. Set it with
`hivectl agents pause <name>` or the dashboard toggle; see
`hivectl agent <name> pause` or the dashboard toggle; see
[persistence](persistence.md#-harnesspaused-per-agent).
1. Long-poll `Recv` on its socket. The host-side broker
(`broker.rs::recv_blocking_batch`) returns immediately if there's