0ae34b1cd0
The operator parts of the persistence and config-changes pages merge into agents/persistence.md. The sqlite tables, state dirs, mounts and migrations move to 4-implementation/agent-state/persistence.md, and the deploy path, meta flake, deploy markers, startup migrations, root container, system messages and autoupdate move to 4-implementation/agent-state/config-changes.md. Links, code comments and nix comments that named the old sections point at the new pages.
70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# Persistence and config changes
|
|
|
|
What survives what, and how a change to an agent's config reaches it.
|
|
|
|
## Persistence
|
|
|
|
The short answer to "does anything disappear": **destroying an agent
|
|
keeps its state, purging it doesn't.**
|
|
|
|
- **`DESTR0Y`** (the default action) stops and removes the container
|
|
but keeps everything on disk — config history, claude login, `/state/`
|
|
notes, harness data. The agent shows up as a tombstone (the K3PT ST4T3
|
|
tab of the dashboard); `swarmctl agent create` with the same name and hive
|
|
recreates it from the kept state, **no re-login needed**.
|
|
- **`PURG3`** (opt-in, from the dashboard or `hivectl agent <name>
|
|
destroy --purge`) is `DESTR0Y` plus wiping all of it — config
|
|
history, claude credentials, `/state/` notes, everything. **No
|
|
undo.** Only reach for this when you actually want the agent gone
|
|
for good. The agent's matrix encryption keys go with the state dir,
|
|
but an account whose key backup is on (see
|
|
[matrix](../swarm/matrix.md)) gets them back from its
|
|
homeserver when it next comes up, so its encrypted history stays
|
|
readable.
|
|
|
|
Beyond that:
|
|
|
|
- **Broker messages**: acked ones vacuum after 30 days; anything
|
|
undelivered or delivered-but-not-yet-acked is always kept, however
|
|
old.
|
|
- **An agent's own `/state/` notes and claude login survive every
|
|
restart and rebuild** — only an explicit purge (or a hive
|
|
`--purge`-style host operation, or the agent's own choices) touches
|
|
them.
|
|
- The **root/bootstrap agent has no guard**: destroying ruth is as final as
|
|
for any agent, and she stays gone until you create her again from the
|
|
swarm dashboard.
|
|
|
|
The tables, state directories, mounts and migrations behind this are in
|
|
[`persistence.md`](../../4-implementation/agent-state/persistence.md).
|
|
|
|
## Config changes
|
|
|
|
A config change is a pull request on the agent's config repo,
|
|
`agent-configs/<name>`. No tool exists for it: opening the PR is the request.
|
|
|
|
1. The agent clones its config repo, edits it (`agent.nix` is the entry point),
|
|
pushes a branch and opens the PR with `hive-forge`. Branch protection lets it
|
|
push branches but not `main`, so it **can't merge its own config PR**. An agent
|
|
can propose a change to another agent's config the same way.
|
|
2. You review the PR on the forge, with its diff, comments and CI status, and
|
|
merge it there. Merging needs membership of the `operators` team in
|
|
`agent-configs`. The team starts empty: add each operator by hand in the forge
|
|
UI.
|
|
3. The merge deploys. The swarm controller finds the hive that runs the agent and
|
|
tells it to rebuild.
|
|
|
|
A merge runs **no evaluation check**. A merged config that doesn't evaluate or
|
|
build fails the rebuild, and the agent's rebuilds keep failing until a fix
|
|
merges. A failed rebuild shows on the hive like any other. A merge whose webhook
|
|
never reaches the controller deploys nothing.
|
|
|
|
You create a brand-new agent at swarm level (`swarmctl agent create`, or the
|
|
swarm UI), not from a hive. The controller seeds its config repo with a default
|
|
`agent.nix`, and every later change is a PR like any other. An agent created
|
|
from an [archetype](../swarm/archetypes.md) gets no config repo: the swarm builds
|
|
it from the archetype's module.
|
|
|
|
The full path, the meta flake, deploy markers, startup migrations, the root
|
|
container, the `system` messages hive-c0re sends and autoupdate:
|
|
[`config-changes.md`](../../4-implementation/agent-state/config-changes.md).
|