# What is a sandbox snapshot?

A sandbox snapshot is a saved copy of a sandbox's machine. You can start new
sandboxes from it later, as many times as you need.

**On Runtime, a snapshot keeps the whole machine by default. With
`mode: "disk"`, it keeps only the files. It costs $0.08 per
decimal GB per 30-day month, on the bytes that only it stores** (rate in force
since 23 September 2026). Blocks that two of your snapshots share are counted
once ([pricing](/docs/pricing#snapshots-images-and-volumes)).

## Why AI agents use snapshots

Setting up a machine is often the slowest part of an agent's task. The setup
includes cloning a repository, installing its dependencies, building it, and
starting a database. A snapshot lets you do that setup once. Every later task
starts from the prepared machine and does not repeat the setup. This suits
evaluation runs, reinforcement learning environments and per-user workspaces.
Each of these should begin from the same known state.

## Snapshot, pause, fork and image

| Mechanism                                   | What it keeps                                  | What you do with it                                |
| ------------------------------------------- | ---------------------------------------------- | -------------------------------------------------- |
| [Pause](/how-to/pause-and-resume-a-sandbox) | Files, memory and processes of one sandbox     | Wake the same sandbox later, on the same host      |
| Snapshot                                    | A saved copy of a sandbox                      | Start new sandboxes from it, any time later        |
| [Fork](/glossary/sandbox-fork)              | Files, memory and running processes            | Running copies now, 1 to 100 at a time |
| [Custom image](/docs/images)                | A filesystem built from a recipe or Dockerfile | Start every sandbox with dependencies installed    |

## Runtime's snapshots in facts

| Fact           | Value                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| Price          | $0.08 per decimal GB per 30-day month, 119 microdollars per GiB-hour |
| Charged on     | The bytes the snapshot alone stores                                                                         |
| Retention      | While you have credit (7 days without credit), or 1 to 365 days with `retentionDays`                        |
| Durability     | Encrypted off-server copy at no extra charge; checked when `backedUp` is `true`                             |
| Taking one     | Pauses a running sandbox for the capture, then wakes it                                                     |
| Where it lives | On its source's server, where sandboxes started from it run                                                 |
| Volumes        | A sandbox with volumes cannot be snapshotted                                                                |

A snapshot's rate is fixed when you make it. A new price applies to it only
from a date announced in advance. Once `backedUp` is `true`, the snapshot can
be restored from its checked copy onto another server. You can do this after
its source server is lost
([storage and backups](/docs/storage#snapshots-survive-their-server)).

Memory snapshots preserve running processes. A disk snapshot keeps only the
root filesystem. Each new sandbox boots fresh, without the saved processes.

## Take one and start from it

```ts check
import { Runtime, Sandbox } from "withruntime";

const runtime = new Runtime();
await using base = await Sandbox.create();
await base.exec("pip install --quiet requests");

const snapshot = await base.snapshot({ name: "with-requests", retentionDays: 7 });
await using later = await runtime.sandboxes.create({ snapshot: snapshot.id });
await runtime.snapshots.delete(snapshot.id);
```

```python check
from withruntime import Runtime

runtime = Runtime()
with runtime.sandboxes.create() as base:
    base.exec("pip install --quiet requests")
    snapshot = base.snapshot(name="with-requests", retention_days=7)
    with runtime.sandboxes.create(snapshot=snapshot["id"]):
        pass
    runtime.snapshots.delete(snapshot["id"])
```

From the CLI, `runtime sandboxes snapshot <id> --name ready` takes a snapshot.
`runtime sandboxes create --snapshot <snapshot>` starts a sandbox from it
([CLI](/docs/cli#images-volumes-and-snapshots)). The full reference is in
[snapshots and forks](/docs/javascript#snapshots-and-forks).

## Related

- [What is a sandbox fork?](/glossary/sandbox-fork)
- [What is a cold start?](/glossary/cold-start)
- [How to pause and resume a sandbox](/how-to/pause-and-resume-a-sandbox)
- [Agent evals and SWE-bench](/use-cases/agent-evals-and-swe-bench)
- [RL environments](/use-cases/rl-environments)

Facts on this page were checked on 25 October 2026.