> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory snapshots

> Capture memory snapshots of files, memory, and devices, wait for readiness, and start machines from saved state.

Use memory snapshots when you want to reuse prepared process state across later machines. Keep the snapshot ID and wait for readiness before restoring work.

## Save a snapshot

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead sandbox snapshot create ID --name prepared
```

The API is `POST /sandboxes/{id}/snapshots`. The response is 202 pending with `snapshotID`, `templateID`, and `buildID`. Keep the snapshot ID.

## Wait for readiness

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead sandbox snapshot get SNAPSHOT_ID
```

Poll until `status` is `ready`. A pending capture is not ready for restored execution. If capture fails, inspect the source machine's `preservation` object before deciding whether to retry.

If snapshot detail reports `retryable: true` and `nextAction: "retry_or_retire"`, retry the existing capture with `bead api POST /snapshots/SNAPSHOT_ID/retry`, then poll its status again. Retire it instead if you no longer need it.

## Snapshot restore

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead create --template SNAPSHOT_ID --size small --timeout 300
```

Use the snapshot's original size in place of `small` when different. Memory restores require the original CPU and memory bounds. Check restored readiness before sending work.

## What is copied

The snapshot captures process memory and the machine's disk and devices. Tenant environment values and secrets already in memory can be retained. Credential-profile inheritance requires explicit permission; a credential-bearing source can refuse capture when consent is missing.

> [!NOTE]
>
> For runner-prompt credentials, authorize capture with `--allow-credential-snapshot`; for a create-time profile, set `metadata["bead.allowCredentialSnapshot"]` to `"true"` in the create API request. Capture with `bead sandbox snapshot create ID --name prepared --inherit-credentials`, then separately set `metadata["bead.inheritCredentials"]` to `"true"` in each restore’s create API request.

Network connections do not migrate transparently. External peers may require reconnecting, and applications bound to an old private address may need to rebind. A restored machine gets its own platform identity.

Saved snapshot capture requires a source with no attached persistent [volume](https://docs.bead.run/platform/volumes.md). Close files and detach the volume before capture; volume contents and retention remain separate from the snapshot.

## Keep or retire a snapshot

Snapshots have no scheduled expiry by default while storage remains funded. Optional expiry and storage grace still apply. See [snapshot retention](https://docs.bead.run/snapshots/retention.md), [fork](https://docs.bead.run/snapshots/fork.md), and [pause and resume](https://docs.bead.run/snapshots/pause-resume.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.