Workspace Snapshots

Every agent runs in an overlayfs workspace, a copy-on-write filesystem view. All writes go to the agent's upper layer; the lower layer (base system) is never modified. Snapshots checkpoint the upper layer, enabling rollback if an agent makes unwanted changes.

How Overlayfs Works

Base filesystem (lower, read-only)
         +
Agent's upper layer (read-write)
         =
Agent's merged view (what the agent sees)

When the agent writes a file, the write goes to the upper layer only. The base filesystem is untouched.

Taking a Snapshot

ash workspace snapshot <agent-id>
# Output: Snapshot 3 taken for agent <uuid>

Snapshots can also be triggered automatically. Set in the manifest:

spec:
  workspace:
    auto_snapshot: true
    snapshot_interval_secs: 300  # every 5 minutes

Listing Snapshots

ash workspace history <agent-id>

Output:

INDEX  CREATED                   SIZE
0      2026-02-22T12:00:00Z      1.2 MB
1      2026-02-22T12:05:00Z      1.8 MB
2      2026-02-22T12:10:00Z      2.1 MB

Index 0 is the oldest, highest index is the most recent.

Viewing Changes

ash workspace diff <agent-id>

Shows files changed in the current overlay vs the last snapshot.

Rolling Back

ash workspace rollback <agent-id> <index>
# e.g.
ash workspace rollback abc-123 1

Rolls back the agent's upper layer to the state at snapshot index 1. The agent continues running with the rolled-back view.

Committing

ash workspace commit <agent-id>

Promotes the current overlay to a permanent snapshot and clears the upper layer. Use this when you want to "bake in" the agent's changes as a new baseline.

Replay Integration

The replay debugger uses workspace snapshots to reconstruct an agent's state at any point in time. See Replay Debugger.

Storage

Workspace data is stored under the agent's working directory, managed by agentd. On cleanup (agent terminate), the upper layer is optionally preserved or discarded based on configuration.