Configuration Version History

Every approved change to a versioned entity is snapshotted before the new value is written. You can list the history for any entity and roll back to a prior version.

Versioned Entities

v1.5.57 ships with agent versioning. The same machinery extends to extensions, connectors, MCP servers, chatrooms, and projects in follow-up releases.

Retention

The repository keeps the most recent 50 versions per entity. Older snapshots are pruned automatically when a new version is added.

Storage

Versions are persisted at <DATA_DIR>/config-versions.json. The file is rewritten on every snapshot and indexed in-memory by (entityKind, entityId) for O(1) listing.

API

GET   /api/config-versions?entityKind=agent&entityId=<agentId>
POST  /api/config-versions/restore   { "versionId": "<id>" }

GET returns the version list ordered newest-first:

{
  "versions": [
    {
      "id": "<versionId>",
      "entityKind": "agent",
      "entityId": "<agentId>",
      "snapshot": { /* frozen agent record at this version */ },
      "note": null,
      "actor": "user",
      "approvalId": null,
      "createdAt": 1713298820000
    },
    ...
  ]
}

POST /api/config-versions/restore writes the frozen snapshot back through the entity's normal update path (so storage normalization runs and other side-effects fire). Returns 501 for entity kinds not yet wired (currently anything other than agent).

CLI

swarmclaw config-versions list --query entityKind=agent,entityId=<agentId>
swarmclaw config-versions restore --json '{"versionId":"<version-id>"}'

Use Cases

• "I broke my agent's tool list — roll back to last week."
• "The orchestrator config drift broke heartbeats. Roll the agent back to before the routing change."
• Review the change log of an agent during a code review or audit.