# Snapshots

> Capture a sandbox's filesystem and configuration as a named, reusable artifact, then spin up fresh sandboxes from it. Ideal for prepared agent and test environments.

A **snapshot** is a named, reusable capture of a sandbox's `/workspace` and its configuration
(template/image, env vars, memory, network mode, startup command). Use it whenever you want a
prepared base environment you can launch many times: install dependencies, write files, set a
[startup command](./concepts.md#lifecycle), snapshot once, then create fresh sandboxes from the
snapshot on demand.

## Snapshot vs. stop/resume vs. fork

These three all preserve files but solve different problems:

| | What it produces | When to use it |
|---|---|---|
| **Stop / resume** | Continues the **same** sandbox id after archiving files | Pause one long-lived sandbox and pick it back up |
| **Snapshot** | A **named, reusable** artifact that creates many new sandboxes later | A golden base image for repeated agent/test runs |
| **[Fork](./forks.md)** | One **immediate copy** into one new sandbox | Branch a running sandbox right now |

All three preserve `/workspace` and configuration. **None** preserve running processes, RAM,
sessions, or preview links.

## Create and restore

```python
from flaxcloud import FlaxClient

flax = FlaxClient()

sb = flax.create_sandbox(
    template="python",
    env={"API_BASE": "https://example.com"},
    startup_command="python3 -m http.server 8000 --bind 0.0.0.0",
)
sb.upload("/workspace/app.py", "print('ready')\n")

snap = sb.create_snapshot("agent-base")
sb.destroy()

# Later, launch a fresh sandbox from the snapshot:
restored = flax.create_sandbox(snapshot_id=snap.id)
print(restored.read_text("/workspace/app.py"))
```

```ts
const sb = await flax.createSandbox({
  template: "python",
  env: { API_BASE: "https://example.com" },
  startupCommand: "python3 -m http.server 8000 --bind 0.0.0.0",
});
await sb.upload("/workspace/app.py", "print('ready')\n");

const snap = await sb.createSnapshot("agent-base");
await sb.destroy();

const restored = await flax.createSandbox({ snapshotId: snap.id });
console.log(await restored.readText("/workspace/app.py"));
```

The restored sandbox comes back with the same env, startup command, and files, so a snapshotted dev
server or preview comes up on its own.

## List and delete

```python
for s in flax.list_snapshots():
    print(s.id, s.name, s.size_bytes)

flax.delete_snapshot(snap.id)
```

```ts
const snapshots = await flax.listSnapshots();
await flax.deleteSnapshot(snap.id);
```

## HTTP API

| Method | Path | Purpose |
|--------|------|---------|
| `POST`   | `/v1/sandboxes/{id}/snapshots` | Create a snapshot from a sandbox. |
| `GET`    | `/v1/snapshots` | List your snapshots. |
| `GET`    | `/v1/snapshots/{id}` | Get one snapshot. |
| `DELETE` | `/v1/snapshots/{id}` | Delete a snapshot. |

To launch from a snapshot, create a sandbox with `{"snapshot_id": "snap_…"}`. See the
[API reference](./api.md).

## Notes

- Snapshot storage counts against your plan's storage limit. Delete snapshots you no longer need.
- The async clients mirror the same surface (`await sb.create_snapshot(...)`,
  `await flax.list_snapshots()`).
- For a one-off branch of a live sandbox instead of a reusable artifact, use a [fork](./forks.md).