mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs/2-handbook/agents/persistence.md
iris 0ae34b1cd0 docs: persistence and config changes become one operator page 
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.
2026-11-11 01:50:35 +01:00

3.4 KiB
Raw Blame History

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) 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.

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 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.