Sandbox forking - E2B Docs

Forking lets you create running copies of a sandbox in a single call. 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.

Fork flow

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 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

You can fork a running sandbox instance. The method returns a list with one entry per requested fork.

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')
}

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.

import { Sandbox } from 'e2b'

// Fork by sandbox ID
const forks = await Sandbox.fork(sandboxId)

from e2b import Sandbox

# Fork by sandbox ID
forks = Sandbox.fork(sandbox_id)

You can also fork a sandbox from the terminal with the E2B CLI. The command prints the ID of each new sandbox on its own line.

e2b sandbox fork <sandboxID>

Create multiple forks

Use count to boot several sandboxes from the same snapshot in one call. With the SDKs and the CLI you can request up to 20 forks at once. The count must also be lower than your team’s concurrent sandbox limit, because the original sandbox keeps running and uses one slot.

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)
  }
}

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.

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)
}

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 timeoutMs (JavaScript) / timeout (Python) option sets how long the new forked sandboxes live and defaults to 15 seconds. It applies to the forks only - the original sandbox’s expiration is not changed.

import { Sandbox } from 'e2b'

const forks = await sandbox.fork({ count: 2, timeoutMs: 60_000 }) // 60 seconds

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	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 when you want a durable checkpoint to create sandboxes from later.

​Fork flow

​Fork a sandbox

​Create multiple forks

​Handle failed forks

​Fork timeout

​Forking vs. Snapshots

Fork flow

Fork a sandbox

Create multiple forks

Handle failed forks

Fork timeout

Forking vs. Snapshots