> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Snapshots

> Save and restore sandbox state with Islo snapshots.

Snapshots let you capture the complete state of a running sandbox and restore it later. This is useful for creating checkpoints before risky changes, sharing a known-good environment, or quickly spinning up pre-configured sandboxes.

## Creating Snapshots

Save a snapshot of a running sandbox:

```bash
islo snapshot save my-sandbox
```

The snapshot captures the entire filesystem state:

* All files across the sandbox filesystem
* Installed runtimes and dependencies
* System and environment configuration

### Custom Snapshot Names

By default, snapshot names are auto-generated. Use `--name` for a custom name:

```bash
islo snapshot save my-sandbox --name before-refactor
islo snapshot save my-sandbox --name v1-release
```

## Listing Snapshots

View all your snapshots:

```bash
islo snapshot ls
```

**Example output:**

```
NAME                      STATUS     SIZE         CREATED
before-refactor           ready      2.1 GB       2026-03-15 10:30
my-sandbox-20260315       ready      1.8 GB       2026-03-14 09:00
v1-release                ready      2.4 GB       2026-03-10 14:22
```

### JSON Output

For scripting:

```bash
islo snapshot ls --output json
```

## Restoring from Snapshots

Create a new sandbox from a snapshot using `--snapshot`:

```bash
islo use new-sandbox --snapshot before-refactor
```

This creates a new sandbox with all the state from the snapshot:

* Files are restored to `/workspace`
* Runtimes and dependencies are already in place — `setup_script` does not re-run
* Configuration is applied

### Combining with Other Options

You can combine `--snapshot` with other flags:

```bash
# Restore and run with an agent
islo use debug-env --snapshot production-state --agent claude

# Restore with a specific working directory
islo use test-sandbox --snapshot before-refactor --workdir /workspace/api

# Restore and run a command
islo use ci-check --snapshot v1-release -- npm test
```

## Deleting Snapshots

Remove snapshots you no longer need:

```bash
# Delete single snapshot
islo snapshot rm before-refactor

# Delete multiple snapshots
islo snapshot rm old-snap-1 old-snap-2 old-snap-3

# Force delete without confirmation
islo snapshot rm before-refactor -f
```

**Aliases:** `islo snapshot delete`

## Use Cases

### Checkpoint Before Risky Changes

```bash
# Save current state
islo snapshot save my-project --name before-migration

# Make risky changes...
islo use my-project -- ./run-migration.sh

# If something breaks, restore
islo use my-project-restored --snapshot before-migration
```

### CI/CD Base Images

```bash
# Create a snapshot with all dependencies installed
islo use ci-base -- npm install && pip install -r requirements.txt
islo snapshot save ci-base --name deps-installed

# CI jobs start from snapshot (faster)
islo use ci-$BUILD_ID --snapshot deps-installed -- npm test
```

### Debugging Production Issues

```bash
# Snapshot production-like state
islo snapshot save prod-replica --name issue-123

# Multiple developers can investigate independently
islo use alice-debug --snapshot issue-123 --agent claude
islo use bob-debug --snapshot issue-123
```

## Command Reference

| Command                                      | Description                         |
| -------------------------------------------- | ----------------------------------- |
| `islo snapshot save <sandbox>`               | Save snapshot (auto-generated name) |
| `islo snapshot save <sandbox> --name <name>` | Save with custom name               |
| `islo snapshot ls`                           | List all snapshots                  |
| `islo snapshot rm <name>`                    | Delete a snapshot                   |
| `islo snapshot rm <name> -f`                 | Force delete without confirmation   |
| `islo use <name> --snapshot <snap>`          | Create sandbox from snapshot        |

## Notes

* Snapshots are stored securely in Islo's infrastructure
* Snapshot size depends on your `/workspace` contents and installed tools
* Restoring from a snapshot creates a new sandbox (doesn't overwrite existing)
* Snapshots are scoped to your tenant/organization