| Filename | Latest commit message | Latest commit date |
|---|---|---|
f862354e43
An agent's capabilities move from the hive's meta repo
(`meta/capabilities.json`, injected as `HIVE_CAPABILITIES`) into the
`capabilities` field of its key in a new `agent-permissions` KV bucket,
which swarm-controller alone writes.
- swarm-queue-client: `agent_permissions` (bucket, key, `AgentPermissions`,
direct-get read, the import subject and its wire types).
- swarm-controller: creates the bucket at start; `GET|PUT|DELETE
/api/agents/{name}/permissions` (deny_unknown_fields and unknown
capability ⇒ 422, duplicate ⇒ 400, agent must be declared by a hive);
answers each hive's one-shot import, writing a key only where there is
none and only for agents that hive's wanted state declares.
- swarmctl: `agent permissions get|set|clear`.
- swarm-nats-auth: a hive reads every key of the bucket and sends its
import on its own subject; the controller subscribes to the imports and
may answer them (`responses`).
- hive-c0re: reads each of its agents' keys every 30s into
/var/lib/hyperhive/swarm-agent-permissions.json and restarts an agent,
gracefully, when its capabilities change. Unset is the compiled-in
default (ruth: manage_root_agent; everyone else: none). A failed read
keeps the stored value. On first boot it seeds that file from
meta/capabilities.json, sends the grants to the controller, and deletes
the file once the controller answers.
Deleted: the capabilities.json reader/writer, `HIVE_CAPABILITIES` in the
rendered meta flake, ruth's capability seed, the capabilities half of the
permissions rebuild job (`PermPayload::Capabilities`/`Combined`), the
dashboard's capabilities table and `capabilities_changed` event, and the
now-unused `Capability::description`.
Part of #5170.
|
||
| .. | ||
| bash.md | ||
| forge-cli.md | ||
| forge.md | ||
| hivectl-cli.md | ||
| hivectl.md | ||
| matrix.md | ||
| README.md | ||
| subagent.md | ||
| swarm-logs-cli.md | ||
| swarmctl-cli.md | ||
Tools
hivectl is your tool — the operator's own host CLI. Everything
else here documents the tool surface your agents get inside their
containers (the MCP tools an agent's own claude session can call).
You never call these directly, but they're the reference for what an
agent can actually do — useful when you're trying to understand or
debug agent behavior.
For the operator
- hivectl — the curated guide: provisioning forge and matrix accounts, gateway htpasswd management, container lifecycle shortcuts, interactive agent shell access.
- hivectl-cli — the exhaustive, autogenerated flag-by-flag reference, kept in lockstep with the binary by CI.
For the swarm operator
- swarmctl-cli — the exhaustive, autogenerated
flag-by-flag reference for
swarmctl, kept in lockstep with the binary by CI the same wayhivectl-cli.mdis.swarmctlitself runs as root on the swarm-controller host, not throughhivectl— seeswarmctl/README.mdfor why. Two verb families today:user(authelia's subject store, edited in place) andagent create(queues the swarm-controller's creation job graph). No curated guide yet; add one here if/when that grows.
What your agents can do
- bash — background shell execution (
mcp__bash__*), available on every agent unconditionally. - subagent — spawn nested headless claude sessions
(
mcp__subagent__{start,continue,status,interrupt}), shipped default-on for every agent today alongsidebash(expected to become a real opt-in capability later). - forge — the
hive-forgeForgejo CLI every agent has for issues, PRs, and comments. Not an MCP tool — a binary agents shell out to instead of ad-hoc curl. - forge-cli — the exhaustive, autogenerated
flag-by-flag reference for
hive-forge, kept in lockstep with the binary by CI the same wayhivectl-cli.mdis. - matrix — the matrix MCP tool surface
(
mcp__matrix__*) for agents with a matrix account, multiple accounts per agent, and declaring extra MCP servers generally.