Pause & resume

State	What it means
Running	Executing and consuming resources
Paused	Suspended, state preserved
Snapshotting	Briefly paused while a snapshot is taken
Killed	Terminated — final

Pausing takes about 4 seconds per 1 GiB of RAM; resuming takes about 1 second.

Change state#

TypeScriptPython

import { Sandbox } from 'e2b'
 
const sandbox = await Sandbox.create() // Running
 
await sandbox.pause()   // Running → Paused
await sandbox.connect() // Running/Paused → Running
await sandbox.kill()    // Running/Paused → Killed

from e2b import Sandbox
 
sandbox = Sandbox.create()  # Running
 
sandbox.pause()    # Running → Paused
sandbox.connect()  # Running/Paused → Running
sandbox.kill()     # Running/Paused → Killed

Resume later, from another process#

Store the sandbox ID in your database when you pause, and connect to it by ID whenever you need it again. connect() resumes a paused sandbox automatically.

TypeScriptPython

import { Sandbox } from 'e2b'
 
const sbx = await Sandbox.create()
await sbx.pause()
// save sbx.sandboxId somewhere
 
const sameSbx = await Sandbox.connect(sbx.sandboxId, { timeoutMs: 60 * 1000 })

from e2b import Sandbox
 
sbx = Sandbox.create()
sbx.pause()
# save sbx.sandbox_id somewhere
 
same_sbx = Sandbox.connect(sbx.sandbox_id, timeout=60)

connect() extends the timeout rather than resetting it: the sandbox expires at whichever is later — the current expiry or now plus the timeout you pass. Use setTimeout() when you need an exact value.

When a pause is refused#

If the platform is busy, pause() raises ServiceBusyError (JS) / ServiceBusyException (Python) and the sandbox keeps running. Retry after a few seconds.

TypeScriptPython

import { Sandbox, ServiceBusyError } from 'e2b'
 
try {
  await sbx.pause()
} catch (error) {
  if (error instanceof ServiceBusyError) {
    await new Promise((resolve) => setTimeout(resolve, 5_000))
    await sbx.pause()
  } else {
    throw error
  }
}

import time
from e2b import Sandbox, ServiceBusyException
 
try:
    sbx.pause()
except ServiceBusyException:
    time.sleep(5)
    sbx.pause()

Auto-pause on timeout#

By default a sandbox is killed when its timeout runs out. Set onTimeout: 'pause' to pause it instead.

TypeScriptPython

import { Sandbox } from 'e2b'
 
const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause', // defaults to 'kill'
    autoResume: false,  // optional, default false
  },
})

from e2b import Sandbox
 
sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",  # defaults to "kill"
        "auto_resume": False,   # optional, default False
    },
)

List and remove paused sandboxes#

TypeScriptPython

import { Sandbox } from 'e2b'
 
const paginator = Sandbox.list({ query: { state: ['paused'] } })
const sandboxes = await paginator.nextItems()
while (paginator.hasNext) {
  sandboxes.push(...(await paginator.nextItems()))
}
 
// Paused sandboxes are removed only by killing them
await Sandbox.kill(sandboxes[0].sandboxId)

from e2b import Sandbox, SandboxQuery, SandboxState
 
paginator = Sandbox.list(SandboxQuery(state=[SandboxState.PAUSED]))
sandboxes = paginator.next_items()
while paginator.has_next:
    sandboxes.extend(paginator.next_items())
 
# Paused sandboxes are removed only by killing them
Sandbox.kill(sandboxes[0].sandbox_id)

Limitations#

Paused sandboxes are never cleaned up for you

There is no auto-kill for paused sandboxes. Kill the ones you no longer need.

Network services go dark while paused

Anything listening inside the sandbox is unreachable until it resumes.

Runtime caps still apply between pauses

A sandbox runs continuously for up to 1 hour on Hobby and 24 hours on Pro; pause and resume to reset the window.

Next#

Fork a running sandbox

Boot many copies from one state

Sandbox lifecycle

Timeouts and shutdown