|
1 | 1 | --- |
2 | 2 | title: "Sandbox forking" |
3 | 3 | sidebarTitle: Forking |
4 | | -description: Checkpoint a running sandbox and boot new sandboxes from that exact state in a single call. |
| 4 | +description: Snapshot a running sandbox and boot new sandboxes from that exact state in a single call. |
5 | 5 | --- |
6 | 6 |
|
7 | 7 | Forking lets you create running copies of a sandbox in a single call. |
8 | | -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. |
| 8 | +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. |
9 | 9 |
|
10 | 10 | 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. |
11 | 11 |
|
12 | 12 | ## Fork flow |
13 | 13 |
|
14 | 14 | ```mermaid actions={false} |
15 | 15 | graph LR |
16 | | - A[Running Sandbox] -->|fork| B[Checkpointing] |
| 16 | + A[Running Sandbox] -->|fork| B[Snapshotting] |
17 | 17 | B --> A |
18 | 18 | B -->|count = N| C[Fork 1] |
19 | 19 | B --> D[Fork 2] |
20 | 20 | B --> E[Fork N] |
21 | 21 | ``` |
22 | 22 |
|
23 | | -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. |
| 23 | +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. |
24 | 24 |
|
25 | 25 | <Warning> |
26 | 26 | 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) |
77 | 77 |
|
78 | 78 | ## Create multiple forks |
79 | 79 |
|
80 | | -Use `count` to boot several sandboxes from the same checkpoint in one call. You can request up to 100 forks at once. |
| 80 | +Use `count` to boot several sandboxes from the same snapshot in one call. You can request up to 100 forks at once. |
81 | 81 |
|
82 | 82 | <CodeGroup> |
83 | 83 | ```js JavaScript & TypeScript highlight={5} |
@@ -162,7 +162,7 @@ Forking is a one-call shortcut for the common snapshot pattern: capture a runnin |
162 | 162 | | | Forking | Snapshots | |
163 | 163 | |---|---|---| |
164 | 164 | | Result | Running sandboxes, ready to use | A persistent snapshot ID | |
165 | | -| Reuse | Checkpoint is used once, for this call's forks | Snapshot can spawn sandboxes any time later | |
| 165 | +| Reuse | Snapshot is used once, for this call's forks | Snapshot can spawn sandboxes any time later | |
166 | 166 | | Steps | One call | `createSnapshot()` / `create_snapshot()`, then `Sandbox.create()` per sandbox | |
167 | 167 |
|
168 | 168 | 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. |
0 commit comments