Agents
Guide

Agent Restore Points

Capture, inspect, and restore point-in-time snapshots of an Agent workspace, configuration pins, and state using durable archive jobs.

For
Agent operators, Organization administrators, and deployment engineers
On this page
  1. Overview
  2. How capture works
  3. Restoring an Agent
  4. Permissions
  5. Restore execution and volume detachment
  6. Related documentation

Capture, inspect, and restore point-in-time snapshots of an Agent's state, configuration, and workspace without specialized CSI storage drivers.

Overview

Agent Restore Points capture an Agent's workspace files, configuration version, and state into durable archives. Following ADR 2026-09-10, Agent Barn uses Kubernetes tar Jobs to archive and restore volume contents directly to object storage, removing any dependency on cluster-level VolumeSnapshot or CSI drivers.

How capture works

When an authorized user captures a restore point:

  • State Snapshot: Agent Barn records the current pinned Template version, model override, and active Skill assignments.
  • Volume Archive Job: A transient Kubernetes Job mounts the Agent's persistent volume read-only, archives workspace content, and writes the resulting tar archive to durable storage.
  • Plugin Store Protection: Workspace artifacts and runtime configurations are preserved while ephemeral caches are excluded from the archive.

Restoring an Agent

Restoring from a restore point returns the Agent to an exact past state:

  • The Agent must be in a STOPPED state before running a restore job.
  • Agent Barn waits for the running pod to cleanly release the persistent volume before launching the restore job.
  • The restore Job unpacks the archived files onto the volume, replaces configuration pins, and clears any previous ERROR state.

Permissions

Creating a restore point or restoring an Agent requires agent.update authority. Viewing available restore points requires activity.read access.

See Manage the Agent lifecycle, Configure an Agent, and Troubleshoot self-hosting.

Restore execution and volume detachment

When restoring an Agent, Agent Barn halts the running Agent workload and waits for the Agent pod to fully release its PersistentVolumeClaim before launching the restore Job. This release wait ensures ReadWriteOnce (RWO) storage volumes avoid multi-attach errors in Kubernetes. Once detached, the restore Job untars the archive, synchronizes configuration pins, and restarts the workload cleanly.

Documentation