Skip to main content

​
Snapshots

Snapshots capture a point-in-time copy of your sandbox’s filesystem. Use them to save progress, create checkpoints, fork experiments, and share state.

​
Creating Snapshots

​
CLI

caged snapshot create cage-a1b2c3d4 --name "after-setup"

​
API

curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/snapshots \
  -H "Authorization: Bearer caged_sk_..." \
  -d '{"name": "after-setup"}'

​
Auto-Snapshots

A snapshot is automatically created when a sandbox is paused (via caged pause or idle timeout). This ensures you can always restore to the exact state before sleep.

​
Listing Snapshots

caged snapshot list cage-a1b2c3d4

ID               NAME           SIZE      CREATED
snap-e5f6g7h8    after-setup    50 MB     2 hours ago
snap-i9j0k1l2    pre-refactor   48 MB     1 hour ago
snap-m3n4o5p6    auto-pause     52 MB     30 minutes ago

​
Restoring

Restore a snapshot into the same or a different sandbox: 
# Restore to the original sandbox
caged snapshot restore snap-e5f6g7h8

# Restore to a different sandbox
caged snapshot restore snap-e5f6g7h8 --to cage-x1y2z3w4
Restoring overwrites the target sandbox’s current filesystem. Create a snapshot first if you need to preserve the current state.

​
Forking

Create a new sandbox from a snapshot — useful for branching experiments: 
# Create a new sandbox from a snapshot
caged up --from-snapshot snap-e5f6g7h8
This creates a new sandbox with:
  • The same template and resources as the original
  • The snapshot’s filesystem pre-loaded
  • A fresh session history

​
Downloading

Export a snapshot as a .tar.gz archive: 
caged snapshot download snap-e5f6g7h8 --output ./my-snapshot.tar.gz
The download URL is pre-signed and expires after 1 hour.

​
Deleting

caged snapshot delete snap-e5f6g7h8

​
Limits

LimitValue
Snapshots per sandbox20
Total storage per account10 GB
Max single snapshot size2 GB
Download URL expiry1 hour

​
Use Cases

​
Checkpoint Before Risky Changes

caged snapshot create cage-a1b2c3d4 --name "before-refactor"
# Run risky agent task...
# If it goes wrong:
caged snapshot restore snap-before-refactor

​
Compare Agent Approaches

# Snapshot the starting state
caged snapshot create cage-a1b2c3d4 --name "baseline"

# Fork two experiments
caged up --from-snapshot snap-baseline   # cage-experiment-1
caged up --from-snapshot snap-baseline   # cage-experiment-2

# Run different agents in each, compare results

​
Share State With Team

caged snapshot download snap-e5f6g7h8 --output ./snapshot.tar.gz
# Share the archive, teammate can import it