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

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