From e27886a35f51ab391be3b948da9865fa38d1eee8 Mon Sep 17 00:00:00 2001 From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com> Date: Wed, 15 Jul 2026 13:00:49 +0200 Subject: [PATCH 1/5] docs(sandbox): add Forking page for sandbox.fork() Documents the new sandbox fork SDK methods (e2b-dev/E2B#1554): checkpoint a running sandbox in place and boot N copies from it. Adds the page to the Sandbox nav group and cross-links it from the Snapshots use cases. Co-Authored-By: Claude Fable 5 --- docs.json | 1 + docs/sandbox/fork.mdx | 174 +++++++++++++++++++++++++++++++++++++ docs/sandbox/snapshots.mdx | 2 +- 3 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 docs/sandbox/fork.mdx diff --git a/docs.json b/docs.json index e43ba751..77ef7cb2 100644 --- a/docs.json +++ b/docs.json @@ -125,6 +125,7 @@ "docs/sandbox/lifecycle-events-webhooks", "docs/sandbox/persistence", "docs/sandbox/snapshots", + "docs/sandbox/fork", "docs/sandbox/auto-resume", "docs/sandbox/filesystem-only-snapshots", "docs/sandbox/git-integration", diff --git a/docs/sandbox/fork.mdx b/docs/sandbox/fork.mdx new file mode 100644 index 00000000..5910a16e --- /dev/null +++ b/docs/sandbox/fork.mdx @@ -0,0 +1,174 @@ +--- +title: "Sandbox forking" +sidebarTitle: Forking +--- + +Forking lets you create running copies of a sandbox in a single call. +The sandbox is checkpointed in place — briefly paused, snapshotted with its full filesystem and memory state, and resumed — and new sandboxes boot from that checkpoint. + +Each fork is an independent sandbox with its own ID and timeout. It starts with the exact state the original had at the moment of the fork — files, running processes, loaded variables, and data — and diverges from there. The original sandbox keeps running with its ID and expiration untouched. + +## Fork flow + +```mermaid actions={false} +graph LR + A[Running Sandbox] -->|fork| B[Checkpointing] + B --> A + B -->|count = N| C[Fork 1] + B --> D[Fork 2] + B --> E[Fork N] +``` + +The snapshot is captured once regardless of how many forks you request, so forking into many sandboxes costs the same single checkpoint on the original. + + +During the fork, the original sandbox is temporarily paused and resumed. This causes all active connections (e.g. WebSocket, PTY, command streams) to be dropped. Make sure your client handles reconnection properly. + + +## Fork a sandbox + +You can fork a running sandbox instance. The method returns a list with one entry per requested fork. + + +```js JavaScript & TypeScript +import { Sandbox } from 'e2b' + +const sandbox = await Sandbox.create() +await sandbox.files.write('/home/user/state.txt', 'shared state') + +// Fork the sandbox +const [fork] = await sandbox.fork() +if (fork instanceof Sandbox) { + // The fork starts with the original's files, processes, and memory + await fork.commands.run('cat /home/user/state.txt') +} +``` +```python Python +from e2b import Sandbox + +sandbox = Sandbox.create() +sandbox.files.write('/home/user/state.txt', 'shared state') + +# Fork the sandbox +fork, = sandbox.fork() +if isinstance(fork, Sandbox): + # The fork starts with the original's files, processes, and memory + fork.commands.run('cat /home/user/state.txt') +``` + + +You can also fork by sandbox ID using the static method. + + +```js JavaScript & TypeScript +import { Sandbox } from 'e2b' + +// Fork by sandbox ID +const forks = await Sandbox.fork(sandboxId) +``` +```python Python +from e2b import Sandbox + +# Fork by sandbox ID +forks = Sandbox.fork(sandbox_id) +``` + + +## Create multiple forks + +Use `count` to boot several sandboxes from the same checkpoint in one call. You can request up to 100 forks at once. + + +```js JavaScript & TypeScript highlight={5} +import { Sandbox } from 'e2b' + +const sandbox = await Sandbox.create() + +const forks = await sandbox.fork({ count: 3 }) + +for (const fork of forks) { + if (fork instanceof Sandbox) { + console.log('Forked sandbox:', fork.sandboxId) + } +} +``` +```python Python highlight={5} +from e2b import Sandbox + +sandbox = Sandbox.create() + +forks = sandbox.fork(count=3) + +for fork in forks: + if isinstance(fork, Sandbox): + print('Forked sandbox:', fork.sandbox_id) +``` + + +## Handle failed forks + +Each fork succeeds or fails independently. Instead of throwing on the first failure, the returned list contains a connected sandbox for each fork that started and an error value for each fork that didn't — so a partial failure doesn't throw away the successful forks. + + +```js JavaScript & TypeScript +import { Sandbox } from 'e2b' + +const results = await sandbox.fork({ count: 5 }) + +const forks = results.filter((r) => r instanceof Sandbox) +const errors = results.filter((r) => !(r instanceof Sandbox)) + +for (const error of errors) { + console.error('Fork failed:', error.message) +} +``` +```python Python +from e2b import Sandbox + +results = sandbox.fork(count=5) + +forks = [r for r in results if isinstance(r, Sandbox)] +errors = [r for r in results if not isinstance(r, Sandbox)] + +for error in errors: + print('Fork failed:', error) +``` + + +If the request fails as a whole (for example, the sandbox does not exist), the method throws instead of returning error values. + +## Fork timeout + +The timeout sets how long the new forked sandboxes live and defaults to 5 minutes, like `Sandbox.create()`. It applies to the forks only — the original sandbox's expiration is not changed. + + +```js JavaScript & TypeScript +import { Sandbox } from 'e2b' + +const forks = await sandbox.fork({ count: 2, timeoutMs: 60_000 }) // 60 seconds +``` +```python Python +from e2b import Sandbox + +forks = sandbox.fork(count=2, timeout=60) # 60 seconds +``` + + +## Forking vs. Snapshots + +Forking is a one-call shortcut for the common snapshot pattern: capture a running sandbox and immediately boot new sandboxes from the capture. + +| | Forking | Snapshots | +|---|---|---| +| Result | Running sandboxes, ready to use | A persistent snapshot ID | +| Reuse | Checkpoint is used once, for this call's forks | Snapshot can spawn sandboxes any time later | +| Steps | One call | `createSnapshot`, then `Sandbox.create` per sandbox | + +Use forking when you want running copies right now. Use [snapshots](/docs/sandbox/snapshots) when you want a durable checkpoint to create sandboxes from later. + +## Use cases + +- **Parallel exploration** — an agent has reached an interesting state; fork it and try several different approaches at once, each in its own sandbox. +- **Best-of-N sampling** — run the same task in N forks and keep the best result. +- **Safe experiments** — fork before a risky operation and test it in the copy while the original keeps running untouched. +- **Fan-out from expensive setup** — do the slow setup (install dependencies, load a dataset) once, then fork into many workers that all start warm. diff --git a/docs/sandbox/snapshots.mdx b/docs/sandbox/snapshots.mdx index 8e28303d..fa0db41f 100644 --- a/docs/sandbox/snapshots.mdx +++ b/docs/sandbox/snapshots.mdx @@ -189,6 +189,6 @@ Use snapshots when you need to capture or fork live runtime state that depends o - **Checkpointing agent work** — an AI agent has loaded data and produced partial results in memory. Snapshot it so you can resume or fork from that point later. - **Rollback points** — snapshot before a risky or expensive operation (running untrusted code, applying a migration, refactoring a web app). If it fails, rollback - spawn a fresh sandbox from the snapshot before the operation happened. -- **Forking workflows** — spawn multiple sandboxes from the same snapshot to explore different approaches in parallel. +- **Forking workflows** — spawn multiple sandboxes from the same snapshot to explore different approaches in parallel. To checkpoint and spawn copies in a single call, see [Forking](/docs/sandbox/fork). - **Cached sandboxes** — avoid repeating expensive setup by snapshotting a sandbox that has already loaded a large dataset or started a long-running process. - **Sharing state** — one user or agent configures an environment interactively, snapshots it, and others start from that exact state. From 8e4f2dbd1366edd7cfea2d534ce78079d6fb3116 Mon Sep 17 00:00:00 2001 From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com> Date: Wed, 15 Jul 2026 13:45:04 +0200 Subject: [PATCH 2/5] docs(sandbox): address Bugbot review on Forking page Add description frontmatter, name timeoutMs/timeout in the timeout prose, and include the Python create_snapshot() name in the comparison table. Co-Authored-By: Claude Fable 5 --- docs/sandbox/fork.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/sandbox/fork.mdx b/docs/sandbox/fork.mdx index 5910a16e..8c87a705 100644 --- a/docs/sandbox/fork.mdx +++ b/docs/sandbox/fork.mdx @@ -1,6 +1,7 @@ --- title: "Sandbox forking" sidebarTitle: Forking +description: Checkpoint a running sandbox and boot new sandboxes from that exact state in a single call. --- Forking lets you create running copies of a sandbox in a single call. @@ -139,7 +140,7 @@ If the request fails as a whole (for example, the sandbox does not exist), the m ## Fork timeout -The timeout sets how long the new forked sandboxes live and defaults to 5 minutes, like `Sandbox.create()`. It applies to the forks only — the original sandbox's expiration is not changed. +The `timeoutMs` (JavaScript) / `timeout` (Python) option sets how long the new forked sandboxes live and defaults to 5 minutes, like `Sandbox.create()`. It applies to the forks only — the original sandbox's expiration is not changed. ```js JavaScript & TypeScript @@ -162,7 +163,7 @@ Forking is a one-call shortcut for the common snapshot pattern: capture a runnin |---|---|---| | Result | Running sandboxes, ready to use | A persistent snapshot ID | | Reuse | Checkpoint is used once, for this call's forks | Snapshot can spawn sandboxes any time later | -| Steps | One call | `createSnapshot`, then `Sandbox.create` per sandbox | +| Steps | One call | `createSnapshot()` / `create_snapshot()`, then `Sandbox.create()` per sandbox | Use forking when you want running copies right now. Use [snapshots](/docs/sandbox/snapshots) when you want a durable checkpoint to create sandboxes from later. From ed42e0512194df29b43f6905976044bd3065a9eb Mon Sep 17 00:00:00 2001 From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com> Date: Wed, 15 Jul 2026 14:05:54 +0200 Subject: [PATCH 3/5] docs(sandbox): remove Use cases section from Forking page Co-Authored-By: Claude Fable 5 --- docs/sandbox/fork.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/sandbox/fork.mdx b/docs/sandbox/fork.mdx index 8c87a705..57f36b44 100644 --- a/docs/sandbox/fork.mdx +++ b/docs/sandbox/fork.mdx @@ -166,10 +166,3 @@ Forking is a one-call shortcut for the common snapshot pattern: capture a runnin | Steps | One call | `createSnapshot()` / `create_snapshot()`, then `Sandbox.create()` per sandbox | Use forking when you want running copies right now. Use [snapshots](/docs/sandbox/snapshots) when you want a durable checkpoint to create sandboxes from later. - -## Use cases - -- **Parallel exploration** — an agent has reached an interesting state; fork it and try several different approaches at once, each in its own sandbox. -- **Best-of-N sampling** — run the same task in N forks and keep the best result. -- **Safe experiments** — fork before a risky operation and test it in the copy while the original keeps running untouched. -- **Fan-out from expensive setup** — do the slow setup (install dependencies, load a dataset) once, then fork into many workers that all start warm. From 99bd2c50bf8f4f2abefe97d3ed5aa28b0768080a Mon Sep 17 00:00:00 2001 From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com> Date: Wed, 15 Jul 2026 14:09:33 +0200 Subject: [PATCH 4/5] docs(sandbox): use snapshot terminology on Forking page The docs consistently call the operation snapshotting; "checkpoint" only appears as an informal noun. Align the Forking page (and its Snapshots cross-link) with that vocabulary. Co-Authored-By: Claude Fable 5 --- docs/sandbox/fork.mdx | 12 ++++++------ docs/sandbox/snapshots.mdx | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sandbox/fork.mdx b/docs/sandbox/fork.mdx index 57f36b44..5ef28e4f 100644 --- a/docs/sandbox/fork.mdx +++ b/docs/sandbox/fork.mdx @@ -1,11 +1,11 @@ --- title: "Sandbox forking" sidebarTitle: Forking -description: Checkpoint a running sandbox and boot new sandboxes from that exact state in a single call. +description: Snapshot a running sandbox and boot new sandboxes from that exact state in a single call. --- Forking lets you create running copies of a sandbox in a single call. -The sandbox is checkpointed in place — briefly paused, snapshotted with its full filesystem and memory state, and resumed — and new sandboxes boot from that checkpoint. +The sandbox is snapshotted in place — briefly paused, captured with its full filesystem and memory state, and resumed — and new sandboxes boot from that snapshot. Each fork is an independent sandbox with its own ID and timeout. It starts with the exact state the original had at the moment of the fork — files, running processes, loaded variables, and data — and diverges from there. The original sandbox keeps running with its ID and expiration untouched. @@ -13,14 +13,14 @@ Each fork is an independent sandbox with its own ID and timeout. It starts with ```mermaid actions={false} graph LR - A[Running Sandbox] -->|fork| B[Checkpointing] + A[Running Sandbox] -->|fork| B[Snapshotting] B --> A B -->|count = N| C[Fork 1] B --> D[Fork 2] B --> E[Fork N] ``` -The snapshot is captured once regardless of how many forks you request, so forking into many sandboxes costs the same single checkpoint on the original. +The snapshot is captured once regardless of how many forks you request, so forking into many sandboxes costs the same single snapshot of the original. During the fork, the original sandbox is temporarily paused and resumed. This causes all active connections (e.g. WebSocket, PTY, command streams) to be dropped. Make sure your client handles reconnection properly. @@ -77,7 +77,7 @@ forks = Sandbox.fork(sandbox_id) ## Create multiple forks -Use `count` to boot several sandboxes from the same checkpoint in one call. You can request up to 100 forks at once. +Use `count` to boot several sandboxes from the same snapshot in one call. You can request up to 100 forks at once. ```js JavaScript & TypeScript highlight={5} @@ -162,7 +162,7 @@ Forking is a one-call shortcut for the common snapshot pattern: capture a runnin | | Forking | Snapshots | |---|---|---| | Result | Running sandboxes, ready to use | A persistent snapshot ID | -| Reuse | Checkpoint is used once, for this call's forks | Snapshot can spawn sandboxes any time later | +| Reuse | Snapshot is used once, for this call's forks | Snapshot can spawn sandboxes any time later | | Steps | One call | `createSnapshot()` / `create_snapshot()`, then `Sandbox.create()` per sandbox | Use forking when you want running copies right now. Use [snapshots](/docs/sandbox/snapshots) when you want a durable checkpoint to create sandboxes from later. diff --git a/docs/sandbox/snapshots.mdx b/docs/sandbox/snapshots.mdx index fa0db41f..06a52364 100644 --- a/docs/sandbox/snapshots.mdx +++ b/docs/sandbox/snapshots.mdx @@ -189,6 +189,6 @@ Use snapshots when you need to capture or fork live runtime state that depends o - **Checkpointing agent work** — an AI agent has loaded data and produced partial results in memory. Snapshot it so you can resume or fork from that point later. - **Rollback points** — snapshot before a risky or expensive operation (running untrusted code, applying a migration, refactoring a web app). If it fails, rollback - spawn a fresh sandbox from the snapshot before the operation happened. -- **Forking workflows** — spawn multiple sandboxes from the same snapshot to explore different approaches in parallel. To checkpoint and spawn copies in a single call, see [Forking](/docs/sandbox/fork). +- **Forking workflows** — spawn multiple sandboxes from the same snapshot to explore different approaches in parallel. To snapshot and spawn copies in a single call, see [Forking](/docs/sandbox/fork). - **Cached sandboxes** — avoid repeating expensive setup by snapshotting a sandbox that has already loaded a large dataset or started a long-running process. - **Sharing state** — one user or agent configures an environment interactively, snapshots it, and others start from that exact state. From f5a658e94c575b3164fa6f3ce09a8b36fdcf62b4 Mon Sep 17 00:00:00 2001 From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:09:17 +0200 Subject: [PATCH 5/5] docs(sandbox): qualify snapshot pause duration on Forking page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace "briefly paused" — the pause scales with disk changes since the last snapshot, so write-heavy workloads pause longer. Co-Authored-By: Claude Fable 5 --- docs/sandbox/fork.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sandbox/fork.mdx b/docs/sandbox/fork.mdx index 5ef28e4f..c03dbbe6 100644 --- a/docs/sandbox/fork.mdx +++ b/docs/sandbox/fork.mdx @@ -5,7 +5,7 @@ description: Snapshot a running sandbox and boot new sandboxes from that exact s --- Forking lets you create running copies of a sandbox in a single call. -The sandbox is snapshotted in place — briefly paused, captured with its full filesystem and memory state, and resumed — and new sandboxes boot from that snapshot. +The sandbox is snapshotted in place — paused, captured with its full filesystem and memory state, and resumed — and new sandboxes boot from that snapshot. Each fork is an independent sandbox with its own ID and timeout. It starts with the exact state the original had at the moment of the fork — files, running processes, loaded variables, and data — and diverges from there. The original sandbox keeps running with its ID and expiration untouched. @@ -23,7 +23,7 @@ graph LR The snapshot is captured once regardless of how many forks you request, so forking into many sandboxes costs the same single snapshot of the original. -During the fork, the original sandbox is temporarily paused and resumed. This causes all active connections (e.g. WebSocket, PTY, command streams) to be dropped. Make sure your client handles reconnection properly. +During the fork, the original sandbox is paused and resumed. The pause duration scales with the amount of disk changes since the last snapshot — write-heavy workloads pause longer. The pause also causes all active connections (e.g. WebSocket, PTY, command streams) to be dropped, so make sure your client handles reconnection properly. ## Fork a sandbox