Sandbox Persistence (Pause and Resume)

The sandbox persistence feature (currently in public beta) allows you to pause a sandbox and resume it later while preserving the full state—including filesystem and memory—for subsequent access.

State Transitions

A sandbox goes through the following states during its lifecycle:

State	Description
Running	Active state, initial state for executing code
Paused	Execution suspended but state preserved
Killed	Terminated, final state (resources released)

State Transition Diagram:

                  betaPause()
    ┌─────────────────────────────────┐
    │                                 ▼
┌───────────┐                   ┌───────────┐
  Running                          Paused
└───────────┘                   └───────────┘
    │   ▲                             │
    │   └─────────────────────────────┘
    │           connect()             │
    │                                 │
    │ kill()                    kill()│
    ▼                                 ▼
┌─────────────────────────────────────────┐
                Killed
└─────────────────────────────────────────┘

Pausing a Sandbox

Use the betaPause() method to pause a sandbox. The pause operation saves the filesystem and memory, including "all running processes, loaded variables, data, etc." You can store the sandbox ID to resume it later.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandbox = await Sandbox.create()

  // Do some work
  await sandbox.commands.run('echo "Hello World" > /tmp/file.txt')

  // Pause the sandbox
  await sandbox.betaPause()

  // Save the sandbox ID for later
  const sandboxId = sandbox.sandboxId
  console.log('Sandbox ID:', sandboxId)
}

main()

Resuming a Sandbox

Use the connect() method with the sandbox ID to resume a paused sandbox. This method automatically restores the paused instance, returning the sandbox to its exact previous state.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandboxId = 'your-sandbox-id' // Use the ID saved when pausing

  // Connect to the paused sandbox
  const sandbox = await Sandbox.connect(sandboxId)

  // Verify the state is restored
  const result = await sandbox.commands.run('cat /tmp/file.txt')
  console.log(result.stdout) // Output: Hello World

  await sandbox.kill()
}

main()

Listing Paused Sandboxes

Use the Sandbox.list() method to query paused sandboxes with a state filter.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // List all paused sandboxes
  const paginator = await Sandbox.list({
    query: { state: ['paused'] }
  })
  const pausedSandboxes = await paginator.nextItems()

  console.log('Paused sandboxes:', pausedSandboxes)
}

main()

Removing a Paused Sandbox

Use the kill() method to permanently remove a paused sandbox.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandboxId = 'your-sandbox-id'

  // Method 1: kill with sandbox object
  const sandbox = await Sandbox.connect(sandboxId)
  await sandbox.kill()

  // Method 2: kill by ID
  await Sandbox.kill(sandboxId)
}

main()

Auto-Pause (Beta)

Sandboxes can be configured with auto-pause via betaCreate()/beta_create(), which automatically pauses the sandbox after a period of inactivity (default 10 minutes). This stops compute consumption while preserving state. The feature remains active after resuming.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandbox = await Sandbox.betaCreate({
    autoPause: {
      enabled: true,
      timeout: 600_000 // 10 minutes in milliseconds
    }
  })

  // Do some work
  await sandbox.commands.run('echo "Hello World"')

  // The sandbox will automatically pause after 10 minutes of inactivity
  // You can later reconnect to it using connect()
}

main()

Network Connection Notes

When paused, all network services become inaccessible. After resuming the sandbox, the client needs to re-establish the connection.