Pause and Resume

Limits

Allowlist: Pause and resume are available only to allowlisted accounts. Make sure that the allowlist is enabled for your account before calling sandbox.pause() or connecting to a paused Sandbox.

• A paused Sandbox enters the deep hibernation state. Deep hibernation has a maximum retention period, and you must connect to the Sandbox to resume it within this period. After the period ends, successful resume is not guaranteed.

• While a Sandbox is paused, no vCPU or memory charges are incurred, but disk charges still apply based on the storage occupied by deep hibernation. For billing rules, see Billing Overview. Write the data that must be retained for a long period to external storage such as OSS or NAS.

Configure automatic pause and resume

When you create a Sandbox, lifecycle specifies how the Sandbox is handled after it times out, and whether a paused Sandbox is automatically resumed when a request arrives.

• on_timeout (Python) / onTimeout (TypeScript): The default value is kill, and the Sandbox is terminated after it times out. If you set the value to pause, the Sandbox is automatically paused on timeout and its current state is retained.

• auto_resume (Python) / autoResume (TypeScript): The default value is False/false. If you set the value to True/true, an SDK operation on a paused Sandbox or an HTTP request to a service inside the Sandbox triggers automatic resume. Calling Sandbox.connect() first is not needed. This option must be used together with on_timeout="pause"/onTimeout: "pause".

The pause mode that retains only the file system cannot yet be configured through keep_memory (Python) / keepMemory (TypeScript).

Enable automatic pause and automatic resume when you create a Sandbox:

from e2b_code_interpreter import Sandbox

sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: "pause",
    autoResume: true,
  },
});

The lifecycle configuration remains effective after the Sandbox is resumed. When the Sandbox times out again, it is paused again. When subsequent activity reaches the Sandbox, it is resumed again. If automatic resume is not enabled, you can still manually resume a paused Sandbox by calling Sandbox.connect().

The timeout in the examples is set by timeout (Python) / timeoutMs (TypeScript) at creation. After the Sandbox is created, call set_timeout (Python) / setTimeout (TypeScript) to adjust it. For configuration details, see Timeouts.

Pause a Sandbox

Pause the current Sandbox:

sandbox.pause()

await sandbox.pause();

After a Sandbox is paused, it is no longer in an active running state. To resume using it later, connect to the existing Sandbox.

Auto-resume on connect

Sandbox.connect(sandboxId) connects to an existing Sandbox. If the Sandbox is paused, it is automatically resumed when you connect.

import os

from e2b_code_interpreter import Sandbox

sandbox = Sandbox.connect(
    sandbox_id,
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)

const sandbox = await Sandbox.connect(sandboxId, {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
});

Recommendations

• Pause a Sandbox when a task needs to preserve context for a short interval between steps.

• After resuming, recheck long-lived connections, process state, and application state before proceeding.

• Pause is not the same as kill. When the task is complete, call sandbox.kill() to release resources.