Sandbox forking

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.

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

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)

Create multiple forks

Use count to boot several sandboxes from the same snapshot in one call. You can request up to 100 forks at once.

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

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

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 5 minutes, like Sandbox.create(). 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

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.

Use forking when you want running copies right now. Use snapshots when you want a durable checkpoint to create sandboxes from later.