> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/snapshots.md).

# Snapshots

Snapshots allow you to capture, roll back, and fork a sandbox by preserving its full state at a specific point in time: process memory, running processes, and the filesystem together.

For the agent workflow built on this, checkpointing before a risky step and undoing it, or forking to try two approaches, see [Undo and Duplicate](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/undo-and-duplicate.md).

You can use snapshots to return to a previous state or create a new sandbox from an existing environment for reproducible workflows and experimentation.

Once a snapshot is taken, you can use it to:

* Roll the same sandbox back to that captured state
* Fork the current live state into a brand-new sandbox

## Create a Snapshot

### Console

1. Go to Agentic Studio → Sandboxes
2. Click on the sandbox you want to snapshot
3. Click the Snapshots tab in the detail panel
4. Click **+ Create Snapshot**
5. Enter an optional name for the snapshot (for example, `before-migration`)
6. Click **Create Snapshot**

The snapshot will appear in the list with a Pending status and transition to Ready once the capture is complete.

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Capture the sandbox's memory and filesystem state
const snapshot = await sandbox.snapshot({ name: "before-migration" });

// Snapshot starts Pending — poll until it reaches Ready
let snap = await neev.sandboxes.getSnapshot(snapshot.id);
while (snap.status === "Pending" || snap.status === "Running") {
  await new Promise((r) => setTimeout(r, 2000));
  snap = await neev.sandboxes.getSnapshot(snapshot.id);
}
console.log(snap.status); // Ready
```

{% endtab %}

{% tab title="Python" %}

```python
import time

# Capture the sandbox's memory and filesystem state
snapshot = sandbox.snapshot({"name": "before-migration"})

# Snapshot starts Pending — poll until it reaches Ready
snap = client.sandboxes.get_snapshot(snapshot.id)
while snap.status in ("Pending", "Running"):
    time.sleep(2)
    snap = client.sandboxes.get_snapshot(snapshot.id)
print(snap.status.value)  # Ready
```

{% endtab %}
{% endtabs %}

**Note:** Always wait for a snapshot to reach Ready before rolling back to it. Rolling back to a Pending snapshot will fail.

## Roll Back a Sandbox

Rolling back returns a sandbox to the state captured in a snapshot. It happens in place: the same sandbox, with the same id, name, and network identity, is overwritten with the snapshot's memory and filesystem state. The processes that were running when the snapshot was taken come back from that moment, and anything started after it is gone.

**Warning:** Rollback is destructive. The sandbox's current state is overwritten and is not automatically archived first. If you might want to come back to the current state, take a snapshot of it before rolling back.

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Roll the sandbox back in place to a Ready snapshot
await sandbox.rollback(snap.id);
```

{% endtab %}

{% tab title="Python" %}

```python
# Roll the sandbox back in place to a Ready snapshot
sandbox.rollback(snap.id)
```

{% endtab %}
{% endtabs %}

## Fork a Sandbox

Forking creates a brand-new sandbox from the current live state of an existing sandbox. The source sandbox keeps running - forking does not pause or affect it in any way. Fork does not require an existing snapshot; it atomically captures the current state and spins up a new sandbox from it.

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Fork the current live state into a new sandbox
const fork = await sandbox.fork("my-forked-sandbox");
await fork.waitUntilReady();
console.log(fork.id, fork.phase); // Ready
```

{% endtab %}

{% tab title="Python" %}

```python
# Fork the current live state into a new sandbox
fork = sandbox.fork("my-forked-sandbox")
fork.wait_until_ready()
print(fork.id, fork.phase)  # Ready
```

{% endtab %}
{% endtabs %}

## List and Delete Snapshots

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// List all snapshots for a sandbox (paginated)
const { items } = await neev.sandboxes.listSnapshots("sandbox-id");

// Delete a snapshot
await neev.sandboxes.deleteSnapshot(snap.id);
```

{% endtab %}

{% tab title="Python" %}

```python
# List all snapshots for a sandbox (paginated)
items = client.sandboxes.list_snapshots("sandbox-id")

# Delete a snapshot
client.sandboxes.delete_snapshot(snap.id)
```

{% endtab %}
{% endtabs %}

## Creating a New Sandbox from a Snapshot

Rollback and fork both act on an existing sandbox. If you instead want a **new** sandbox that starts from a snapshot's state, pass `restore` (the snapshot's UUID; `from_snapshot` is the older name for the same field) when creating it, instead of a template or image - see [Create a Sandbox](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/create-pause-delete-sandboxes.md#starting-from-a-custom-image-or-a-snapshot). The new sandbox's size and region must match the snapshot's origin.

## Rollback vs Fork

|                                | Snapshot + Rollback                                     | Fork                                                       |
| ------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------- |
| **What it does**               | Captures state, rolls the same sandbox back in place    | Branches current live state into a new sandbox             |
| **Source sandbox**             | Continues running (snapshot is independent)             | Continues running unaffected                               |
| **Requires existing snapshot** | Yes - snapshot must be Ready before rolling back        | No - captures live state atomically                        |
| **Use when**                   | You want to roll back the same sandbox to a known state | You want to create a copy of a sandbox without stopping it |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/snapshots.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
