mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

swarmctl: agent set-state declares an agent's wanted state

Browse source 
Wraps PUT /api/hives/{hive}/agents/{agent}/state, the route the swarm UI's
state menu uses. States come from swarm_wire::wanted::AgentState; destroyed
needs --yes.

Closes #6159
This commit is contained in:
atlas 2026-11-07 03:58:39 +01:00 • committed by mara
commit 71d360c9d2
1 changed files with 187 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/2-handbook/reference/swarmctl-cli.md
View file

@ -8,6 +8,7 @@ This document contains the help content for the `swarmctl` command-line program.
* [`swarmctl agent`↴](#swarmctl-agent)
* [`swarmctl agent create`↴](#swarmctl-agent-create)
* [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token)
* [`swarmctl agent set-state`↴](#swarmctl-agent-set-state)
* [`swarmctl agent inference`↴](#swarmctl-agent-inference)
* [`swarmctl agent inference get`↴](#swarmctl-agent-inference-get)
* [`swarmctl agent inference set`↴](#swarmctl-agent-inference-set)
@ -72,6 +73,7 @@ Manage agents across the swarm
* `create` — Queue creation of a new agent on a hive in this swarm
* `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
* `set-state` — Declare the state a hive converges an agent to: `up`, `offline`, `paused` or `destroyed`
* `inference` — Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models
* `permissions` — Show or change the permissions the swarm grants an agent
* `agents-md` — Show an agent's AGENTS.md, or edit it with a diff
@ -132,6 +134,33 @@ Queues and returns, the same way `agent create` does — watch the swarm UI's jo
## `swarmctl agent set-state`
Declare the state a hive converges an agent to: `up`, `offline`, `paused` or `destroyed`.
Writes the swarm's declaration for the agent, the one the swarm UI's state menu writes, and returns once the controller has published it; the hive converges on its own clock. The swarm must already know the agent on `--hive`: this never creates one.
`destroyed` can't be undone, so it needs `--yes`.
No approval gate guards this: the caller is root on the controller's host, or logged in through the swarm domain's SSO gate.
**Usage:** `swarmctl agent set-state [OPTIONS] --hive <HIVE> <AGENT> <STATE>`
###### **Arguments:**
* `<AGENT>` — Agent name
* `<STATE>` — The state to declare: `up`, `offline`, `paused` or `destroyed`
###### **Options:**
* `--hive <HIVE>` — The hive that runs the agent
* `--yes` — Confirm `destroyed`, which can't be undone
* `--controller-socket <PATH>` — swarm-controller's unix socket.
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
## `swarmctl agent inference`
Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models.