---
title: Snapshots
description: "Save, restore, fork, and download sandbox state."
---

# 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

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

### API

```bash
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

```bash
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:

```bash
# Restore to the original sandbox
caged snapshot restore snap-e5f6g7h8

# Restore to a different sandbox
caged snapshot restore snap-e5f6g7h8 --to cage-x1y2z3w4
```

<Warning>
Restoring overwrites the target sandbox's current filesystem. Create a snapshot first if you need to preserve the current state.
</Warning>

## Forking

Create a new sandbox from a snapshot — useful for branching experiments:

```bash
# 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:

```bash
caged snapshot download snap-e5f6g7h8 --output ./my-snapshot.tar.gz
```

The download URL is pre-signed and expires after 1 hour.

## Deleting

```bash
caged snapshot delete snap-e5f6g7h8
```

## Limits

| Limit | Value |
|-------|-------|
| Snapshots per sandbox | 20 |
| Total storage per account | 10 GB |
| Max single snapshot size | 2 GB |
| Download URL expiry | 1 hour |

## Use Cases

### Checkpoint Before Risky Changes

```bash
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

```bash
# 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

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