Add sandbox snapshots documentation

- New docs/sandbox/snapshots.mdx page covering create, list, delete snapshots
- Add snapshots to sidebar navigation
- Update persistence page: replace PNG diagram with Mermaid flowchart including Snapshotting state
- Remove unused images/diagram.png
- Add .tool-versions for mise (Node 24.11.0)

Author: dobrac

.tool-versions

@@ -0,0 +1 @@
+node 24.11.0

docs.json

@@ -89,6 +89,7 @@
               "docs/sandbox/lifecycle-events-api",
               "docs/sandbox/lifecycle-events-webhooks",
               "docs/sandbox/persistence",
+              "docs/sandbox/snapshots",
               "docs/sandbox/git-integration",
               "docs/sandbox/metrics",
               "docs/sandbox/metadata",

docs/sandbox/persistence.mdx

@@ -17,14 +17,28 @@ This includes not only state of the sandbox's filesystem but also the sandbox's
 
 Understanding how sandboxes transition between different states is crucial for managing their lifecycle effectively. Here's a diagram showing the possible state transitions:
 
-<Frame>
-<img src="/images/diagram.png" />
-</Frame>
+```mermaid
+flowchart TD
+    start(( )) -->|Sandbox.create| Running
+
+    Running["<b>Running</b><br/>• Active execution<br/>• Consumes resources"]
+    Paused["<b>Paused</b><br/>• Preserves memory and files<br/>• Cannot execute code"]
+    Snapshotting["<b>Snapshotting</b><br/>• Creates persistent snapshot<br/>• Briefly pauses execution"]
+    Killed["<b>Killed</b><br/>• Resources released<br/>• Cannot be resumed"]
+
+    Running -->|pause| Paused
+    Running -->|createSnapshot| Snapshotting
+    Paused -->|connect| Running
+    Snapshotting -->|snapshot complete| Running
+    Running -->|kill| Killed
+    Paused -->|kill| Killed
+```
 
 ### State descriptions
 
 - **Running**: The sandbox is actively running and can execute code. This is the initial state after creation.
 - **Paused**: The sandbox execution is suspended but its state is preserved.
+- **Snapshotting**: The sandbox is briefly paused while a persistent snapshot is being created. It automatically returns to Running. See [Snapshots](/docs/sandbox/snapshots).
 - **Killed**: The sandbox is terminated and all resources are released. This is a terminal state.
 
 ### Changing sandbox's state

docs/sandbox/snapshots.mdx

@@ -0,0 +1,163 @@
+---
+title: "Sandbox snapshots"
+sidebarTitle: Snapshots
+---
+
+Snapshots let you create a persistent point-in-time capture of a running sandbox, including both its filesystem and memory state.
+You can then use a snapshot to spawn new sandboxes that start from the exact same state.
+
+The original sandbox continues running after the snapshot is created, and a single snapshot can be used to create many new sandboxes.
+
+## Snapshots vs. Pause/Resume
+
+| | Pause/Resume | Snapshots |
+|---|---|---|
+| Effect on original sandbox | Pauses (stops) the sandbox | Sandbox keeps running |
+| Relationship | 1:1 — resume restores the same sandbox | 1:many — snapshot can spawn many new sandboxes |
+| Use case | Suspend and resume a single sandbox | Create a reusable checkpoint |
+
+For pause/resume functionality, see [Persistence](/docs/sandbox/persistence).
+
+## Snapshot flow
+
+```mermaid
+graph LR
+    A[Running Sandbox] -->|createSnapshot| B[Snapshotting]
+    B --> C[Snapshot Created]
+    B --> A
+    C -->|Sandbox.create| D[New Sandbox 1]
+    C -->|Sandbox.create| E[New Sandbox 2]
+    C -->|Sandbox.create| F[New Sandbox N]
+```
+
+The sandbox is briefly paused during the snapshot process but automatically returns to running state.
+
+## Create a snapshot
+
+You can create a snapshot from a running sandbox instance.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from '@e2b/code-interpreter'
+
+const sandbox = await Sandbox.create()
+
+// Create a snapshot from a running sandbox
+const snapshot = await sandbox.createSnapshot()
+console.log('Snapshot ID:', snapshot.snapshotId)
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+
+sandbox = Sandbox.create()
+
+# Create a snapshot from a running sandbox
+snapshot = sandbox.create_snapshot()
+print('Snapshot ID:', snapshot.snapshot_id)
+```
+</CodeGroup>
+
+You can also create a snapshot by sandbox ID using the static method.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from '@e2b/code-interpreter'
+
+// Create a snapshot by sandbox ID
+const snapshot = await Sandbox.createSnapshot(sandboxId)
+console.log('Snapshot ID:', snapshot.snapshotId)
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+
+# Create a snapshot by sandbox ID
+snapshot = Sandbox.create_snapshot(sandbox_id)
+print('Snapshot ID:', snapshot.snapshot_id)
+```
+</CodeGroup>
+
+## Create a sandbox from a snapshot
+
+The snapshot ID can be used directly with `Sandbox.create()` to spawn a new sandbox from the snapshot. The new sandbox starts with the exact filesystem and memory state captured in the snapshot.
+
+<CodeGroup>
+```js JavaScript & TypeScript highlight={5}
+import { Sandbox } from '@e2b/code-interpreter'
+
+const snapshot = await sandbox.createSnapshot()
+
+// Create a new sandbox from the snapshot
+const newSandbox = await Sandbox.create(snapshot.snapshotId)
+```
+```python Python highlight={5}
+from e2b_code_interpreter import Sandbox
+
+snapshot = sandbox.create_snapshot()
+
+# Create a new sandbox from the snapshot
+new_sandbox = Sandbox.create(snapshot.snapshot_id)
+```
+</CodeGroup>
+
+## List snapshots
+
+You can list all snapshots. The method returns a paginator for iterating through results.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from '@e2b/code-interpreter'
+
+const paginator = Sandbox.listSnapshots()
+
+const snapshots = []
+while (paginator.hasNext) {
+  const items = await paginator.nextItems()
+  snapshots.push(...items)
+}
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+
+paginator = Sandbox.list_snapshots()
+
+snapshots = []
+while paginator.has_next:
+    items = paginator.next_items()
+    snapshots.extend(items)
+```
+</CodeGroup>
+
+### Filter by sandbox
+
+You can filter snapshots created from a specific sandbox.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from '@e2b/code-interpreter'
+
+const paginator = Sandbox.listSnapshots({ sandboxId: 'your-sandbox-id' })
+const snapshots = await paginator.nextItems()
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+
+paginator = Sandbox.list_snapshots(sandbox_id="your-sandbox-id")
+snapshots = paginator.next_items()
+```
+</CodeGroup>
+
+## Delete a snapshot
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from '@e2b/code-interpreter'
+
+// Returns true if deleted, false if the snapshot was not found
+const deleted = await Sandbox.deleteSnapshot(snapshot.snapshotId)
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+
+Sandbox.delete_snapshot(snapshot.snapshot_id)
+```
+</CodeGroup>