| Filename | Latest commit message | Latest commit date |
|---|---|---|
f778122f5a
A swarm runs one homeserver and a homeserver has one appservice sender account, so "mint it once" is a property of the thing being minted rather than something a lock has to enforce. That is what makes this account the one to move first: no trigger route, no controller change and no agent list — a boot-time oneshot beside tuwunel is the whole mechanism. `swarm-matrix-minter` runs inside `containers.hive-matrix`, which already holds the appservice token: the rendered registration is bound in read-only because that is how tuwunel is handed it. What the container lacked was an identity of its own, so this adds one — a leaf from the store's CA with a grant of exactly one path, not the hive's leaf, which reads every secret in the store. Both ends of the credential ship here. The minter reads the path it publishes to before it touches the homeserver, and returning on a non-empty read IS the "only once"; `hive-c0re`'s `ensure_hive_user` reads the same path, authenticating with the hive name already in `HYPERHIVE_HIVE_NAME`. The existing mint-then-`M_USER_IN_USE`-login ladder stays as the fallback for a store that is empty, unconfigured or unreachable, which is every swarm deployed before this — so nothing needs backfilling and nothing breaks if the rest of the sequence never lands. The credential is not an admin credential, and is not named like one. It is the access token of the appservice registration's own `sender_localpart` — `@hive:<server_name>`, an account the homeserver creates for itself when it loads the registration. The store path is `swarm/services/matrix/sender-token`, the host path is `matrix/access-token`, and the homeserver no longer runs an `admin_execute` promotion for that account at boot. Everything the hive provisions with it — the Space, the chat room, their hierarchy and join rules, the invites — rides on being the creator of those rooms at power level 100, not on homeserver admin; there is no Synapse admin API here to need, tuwunel has none. Two operations do need an admin *sender* and therefore stop working: `hivectl matrix promote-user` and `hivectl matrix reset-password`, both `!admin …` messages into `#admins:<server>`, plus the password-reset recovery path that an agent with a lost password file falls back to. They are swarm-level operations and are left failing loudly rather than served by an over-privileged token every other call site would also carry. The sweep's own admin-rights check and self-repair go with them: an account that is deliberately not an admin has nothing to check. `ephemeral = false` stays, and hive root can still read the container's filesystem. Accepted: what this buys is identity separation — no hive *process* holds or reads the appservice token — not physical isolation. Refs #4345 |
||
| .. | ||
| bash.md | ||
| forge-cli.md | ||
| forge.md | ||
| hivectl-cli.md | ||
| hivectl.md | ||
| lifecycle.md | ||
| matrix.md | ||
| README.md | ||
| scheduling.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. - lifecycle — listing the agents in a caller's own subtree, plus the approval-gated config-change tools.
- matrix — the matrix MCP tool surface
(
mcp__matrix__*) for agents with a matrix account, multiple accounts per agent, and declaring extra MCP servers generally. - scheduling — scheduled prompts (operator
approval required) and the
get_host_journaldiagnostics tool.