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

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Snapshots

> Save a sandbox’s home files and start the next run from the same point.

A snapshot captures supported home files at one instant. Save a project after installing dependencies or setting up a browser profile. You can close the sandbox and pick up in a later run, or start several independent runs from the same files. The source sandbox can keep working during capture and upload. Later changes stay in the source sandbox.

## Capture and restore

Set `OFFSTAGE_API_KEY` in your environment and install the SDK.

```bash theme={null}
npm install https://api.offstage.cloud/sdk/offstage-cloud-0.3.4.tgz
```

This example saves a file, closes the source sandbox, and reads the file from a new sandbox. Keep the printed snapshot ID for another run.

```js snapshot.mjs theme={null}
import { Sandbox } from "offstage-cloud"

const source = await Sandbox.create()
let saved
try {
  await source.ready()
  await source.files.write("checkpoint.txt", "Ready for the next run")
  saved = await source.createSnapshot({ name: "test-baseline" })
  console.log(saved.id)
} finally {
  await source.kill()
}

const restored = await Sandbox.create({ snapshotId: saved.id })
try {
  await restored.ready()
  console.log(await restored.files.read("checkpoint.txt"))
} finally {
  await restored.kill()
}
```

## Local and durable captures

The SDK waits for local capture before it returns. Use the immutable ID at that point. If the source Mac loses its copy before the upload completes, the snapshot may become unavailable.

Read `await Snapshot.getInfo(id)` with `Snapshot` imported from `offstage-cloud`. When `durableAt` is present, Offstage has verified the encrypted remote copy. A new sandbox can then restore on another compatible Mac. The saved session type (headless or GUI) and macOS major version must match. Downloading the files and starting a desktop can take time. Wait for `ready()` before running commands.

A name such as `test-baseline` selects the latest verified snapshot saved with that name. When you reuse a name, the previous snapshot remains available until the replacement becomes durable, then Offstage removes the old snapshot. Give captures distinct names to keep both.

## Use agent tools

Give Codex or another coding agent the sandbox ID and ask it to save the sandbox and wait for the verified upload. The SDK installed above includes the snapshot CLI. For example, with a ready sandbox ID in `SANDBOX_ID`:

```bash theme={null}
npx --no-install offstage-cloud snapshot create "$SANDBOX_ID" --name test-baseline
```

Use the ID from the result with `npx --no-install offstage-cloud snapshot show SNAPSHOT_ID` to check `durableAt`, and `npx --no-install offstage-cloud snapshot restore SNAPSHOT_ID` to create a new sandbox. The restore prints its ID. Wait for readiness in the SDK before running work, and close that sandbox when finished.

These MCP tool names require an Offstage MCP server that includes snapshot tools (version 0.5.1 or later).

| Action | Tool |
| - | - |
| Capture a ready sandbox | `offstage_snapshot_create` with `sandboxId` and an optional `name` |
| List team snapshots | `offstage_snapshot_list`, optionally filtered by `sandboxId` |
| Read state, size, durability or expiry | `offstage_snapshot_get` with `snapshotId` |
| Restore a new sandbox | `offstage_sandbox_create` with `snapshotId` set to the ID or verified name |
| Check restore readiness | `offstage_sandbox_get` with the **new** `sandboxId` |
| Delete a snapshot | `offstage_snapshot_delete` with `snapshotId` |

## What carries over

* **Project files and tools.** The working directory and supported home files carry over. Recognized Python virtual-environment paths are adjusted for the new home. Flush writes and save open documents before capture. Launch apps and processes again after restore.
* **Browser data.** GUI snapshots include the standalone default keychain Offstage sets up for the sandbox. A restored Chrome profile can use encrypted cookies backed by that keychain. A website can still expire a session or require another sign-in.
* **Fresh on restore.** Safari data, protected app containers, native login and iCloud keychains, device-bound keys, user LaunchAgents and login startup settings are excluded. Headless captures exclude keychains entirely.
* **Secrets.** Select any required Offstage-managed secrets again when creating the restored sandbox. A token copied into a project file or saved in a supported app profile can travel with the snapshot. Treat the contents as accessible to your team.

## Limits and retention

Your team can keep 10 snapshots totaling 20 GB, with a 5 GB limit per snapshot. These sizes are measured before compression. A successful restore renews the 30-day retention period. Offstage sends a warning before deleting an unused snapshot. Read `expiresAt` for its current expiry.

List captures with `await Snapshot.list()`, or filter by `sourceSandboxId`. Delete a capture with `await Snapshot.delete(id)` when you no longer need it. For HTTP response codes and polling, see the [Sandbox API reference](https://offstage.cloud/docs/api/sandboxes.md#capture-and-restore-a-home-snapshot).

## Related guides

* [Computer use on macOS](https://offstage.cloud/docs/computer-use.md)
* [Tasks](https://offstage.cloud/docs/tasks.md)


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