e2b-dev · matthewlouisbrockman · Mar 11, 2026 · Feb 20, 2026 · Feb 20, 2026 · Feb 20, 2026
diff --git a/docs.json b/docs.json
@@ -108,6 +108,7 @@
               "docs/sandbox/lifecycle-events-webhooks",
               "docs/sandbox/persistence",
               "docs/sandbox/snapshots",
+              "docs/sandbox/auto-resume",
               "docs/sandbox/git-integration",
               "docs/sandbox/metrics",
               "docs/sandbox/metadata",

diff --git a/docs/agents/amp.mdx b/docs/agents/amp.mdx
@@ -64,7 +64,7 @@

 const sandbox = await Sandbox.create('amp', {
  envs: { AMP_API_KEY: process.env.AMP_API_KEY },
  timeoutMs: 600_000,
 })

 await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
@@ -180,7 +180,7 @@

 const sandbox = await Sandbox.create('amp', {
  envs: { AMP_API_KEY: process.env.AMP_API_KEY },
  timeoutMs: 600_000,
 })

 // Start a new thread
@@ -191,7 +191,7 @@

 // List threads and get the most recent thread ID
 const threads = await sandbox.commands.run('amp threads list --json')
 const threadId = JSON.parse(threads.stdout)[0].id

 // Continue the thread with a follow-up task
 const followUp = await sandbox.commands.run(
@@ -288,7 +288,7 @@

 <CodeGroup>
 ```bash JavaScript & TypeScript
 npx tsx build.ts
 ```
 ```bash Python
 python build.py
@@ -299,10 +299,10 @@
 
 <CardGroup cols={3}>
   <Card title="Sandbox persistence" icon="clock" href="/docs/sandbox/persistence">
-    Auto-pause, resume, and manage sandbox lifecycle
+    Developer Preview: auto-pause, resume, and manage sandbox lifecycle
   </Card>
   <Card title="Git integration" icon="code-branch" href="/docs/sandbox/git-integration">
     Clone repos, manage branches, and push changes
  </Card>
  <Card title="SSH access" icon="terminal" href="/docs/sandbox/ssh-access">
    Connect to the sandbox via SSH for interactive sessions

diff --git a/docs/agents/claude-code.mdx b/docs/agents/claude-code.mdx
@@ -4,7 +4,7 @@
 icon: "/images/icons/claude-code.svg"
 ---

 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's agentic coding tool. E2B provides a pre-built `claude` template with Claude Code already installed.

 ## CLI

@@ -64,7 +64,7 @@

 const sandbox = await Sandbox.create('claude', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
 })

 await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
@@ -220,7 +220,7 @@

 const sandbox = await Sandbox.create('claude', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
 })

 // Start a new session
@@ -230,7 +230,7 @@

 // Extract session ID from the JSON response
 const response = JSON.parse(initial.stdout)
 const sessionId = response.session_id

 // Continue with a follow-up task
 const followUp = await sandbox.commands.run(
@@ -334,7 +334,7 @@

 const sandbox = await Sandbox.create('claude', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  mcp: {
    browserbase: {
      apiKey: process.env.BROWSERBASE_API_KEY,
      projectId: process.env.BROWSERBASE_PROJECT_ID,
@@ -342,8 +342,8 @@
  },
 })

 const mcpUrl = sandbox.getMcpUrl()
 const mcpToken = await sandbox.getMcpToken()

 await sandbox.commands.run(
  `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`
@@ -437,7 +437,7 @@

 <CodeGroup>
 ```bash JavaScript & TypeScript
 npx tsx build.ts
 ```
 ```bash Python
 python build.py
@@ -451,9 +451,9 @@
     Connect Claude Code to 200+ MCP tools
   </Card>
   <Card title="Sandbox persistence" icon="clock" href="/docs/sandbox/persistence">
-    Auto-pause, resume, and manage sandbox lifecycle
+    Developer Preview: auto-pause, resume, and manage sandbox lifecycle
   </Card>
   <Card title="Git integration" icon="code-branch" href="/docs/sandbox/git-integration">
     Clone repos, manage branches, and push changes
  </Card>
 </CardGroup>
diff --git a/docs/agents/codex.mdx b/docs/agents/codex.mdx
@@ -66,7 +66,7 @@

 const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
  timeoutMs: 600_000,
 })

 await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
@@ -246,19 +246,19 @@

 ## Image input

 Pass screenshots or design mockups with `--image` to give Codex visual context alongside the prompt.

 <CodeGroup>
 ```typescript JavaScript & TypeScript
 import fs from 'fs'
 import { Sandbox } from 'e2b'

 const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
  timeoutMs: 600_000,
 })

 // Upload a design mockup to the sandbox
 await sandbox.files.write(
  '/home/user/mockup.png',
  fs.readFileSync('./mockup.png')
@@ -344,7 +344,7 @@

 <CodeGroup>
 ```bash JavaScript & TypeScript
 npx tsx build.ts
 ```
 ```bash Python
 python build.py
@@ -355,10 +355,10 @@
 
 <CardGroup cols={3}>
   <Card title="Sandbox persistence" icon="clock" href="/docs/sandbox/persistence">
-    Auto-pause, resume, and manage sandbox lifecycle
+    Developer Preview: auto-pause, resume, and manage sandbox lifecycle
   </Card>
   <Card title="Git integration" icon="code-branch" href="/docs/sandbox/git-integration">
     Clone repos, manage branches, and push changes
  </Card>
  <Card title="SSH access" icon="terminal" href="/docs/sandbox/ssh-access">
    Connect to the sandbox via SSH for interactive sessions

diff --git a/docs/agents/openclaw.mdx b/docs/agents/openclaw.mdx
@@ -64,7 +64,7 @@

 const sandbox = await Sandbox.create('openclaw', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
 })

 await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
@@ -168,7 +168,7 @@
 # Soul

 ## Core Truths
 - Be genuinely helpful, not performatively helpful
 - Be resourceful before asking — check the workspace, search the web, read docs

 ## Boundaries
@@ -386,9 +386,9 @@
 
 OpenClaw has a built-in [web UI and chat interface](https://openclaw.ai) served by its gateway. Start it inside a sandbox and connect from your browser.
 
-<Warning>
-This sandbox is created with a 10-minute timeout and auto-pause enabled — after 10 minutes of inactivity it pauses and can be resumed later. See [Sandbox Persistence](/docs/sandbox/persistence) and [Sandbox Lifecycle](/docs/sandbox) for more details.
-</Warning>
+<Warning>
+This sandbox is created with a 10-minute timeout and auto-pause enabled. After 10 minutes of inactivity it pauses and can be resumed later. Pause/resume persistence and auto-resume are currently in **Developer Preview**. See [Sandbox Persistence](/docs/sandbox/persistence) and [Sandbox Lifecycle](/docs/sandbox) for more details.
+</Warning>
 
 <CodeGroup>
 ```typescript JavaScript & TypeScript
@@ -396,8 +396,8 @@

 const sandbox = await Sandbox.betaCreate('openclaw', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  autoPause: true,
  timeoutMs: 10 * 60 * 1000,
 })

 // Start the gateway
@@ -436,7 +436,7 @@
 import { Template, waitForPort } from 'e2b'

 export const template = Template()
  .fromTemplate('openclaw')
  // Optional - start the OpenClaw gateway on sandbox start
  .setStartCmd(
    'openclaw gateway --port 18789 --verbose',
@@ -488,7 +488,7 @@

 <CodeGroup>
 ```bash JavaScript & TypeScript
 npx tsx build.ts
 ```
 ```bash Python
 python build.py
@@ -499,10 +499,10 @@
 
 <CardGroup cols={3}>
   <Card title="Sandbox persistence" icon="clock" href="/docs/sandbox/persistence">
-    Auto-pause, resume, and manage sandbox lifecycle
+    Developer Preview: auto-pause, resume, and manage sandbox lifecycle
   </Card>
   <Card title="Git integration" icon="code-branch" href="/docs/sandbox/git-integration">
     Clone repos, manage branches, and push changes
  </Card>
  <Card title="SSH access" icon="terminal" href="/docs/sandbox/ssh-access">
    Connect to the sandbox via SSH for interactive sessions

diff --git a/docs/agents/opencode.mdx b/docs/agents/opencode.mdx
@@ -64,7 +64,7 @@

 const sandbox = await Sandbox.create('opencode', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
 })

 await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
@@ -122,8 +122,8 @@

 const sandbox = await Sandbox.betaCreate('opencode', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  autoPause: true,
  timeoutMs: 10 * 60 * 1000,
 })

 // Start the OpenCode server
@@ -133,7 +133,7 @@

 // Wait for the server to be ready
 const host = sandbox.getHost(4096)
 const baseUrl = `https://${host}`
 while (true) {
  try {
    await fetch(`${baseUrl}/global/health`)
@@ -208,7 +208,7 @@
 import { Template, waitForPort } from 'e2b'

 export const template = Template()
  .fromTemplate('opencode')
  .setEnvs({
    OPENCODE_SERVER_PASSWORD: 'your-password',
  })
@@ -266,7 +266,7 @@

 <CodeGroup>
 ```bash JavaScript & TypeScript
 npx tsx build.ts
 ```
 ```bash Python
 python build.py
@@ -277,10 +277,10 @@
 
 <CardGroup cols={3}>
   <Card title="Sandbox persistence" icon="clock" href="/docs/sandbox/persistence">
-    Auto-pause, resume, and manage sandbox lifecycle
+    Developer Preview: auto-pause, resume, and manage sandbox lifecycle
   </Card>
   <Card title="Git integration" icon="code-branch" href="/docs/sandbox/git-integration">
     Clone repos, manage branches, and push changes
  </Card>
  <Card title="SSH access" icon="terminal" href="/docs/sandbox/ssh-access">
    Connect to the sandbox via SSH for interactive sessions

diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
@@ -3,7 +3,7 @@
 sidebarTitle: Lifecycle
 ---
 
-Sandboxes stay running as long as you need them. When their timeout expires, they automatically pause to save resources — preserving their full state so you can resume at any time. You can also configure an explicit timeout or shut down a sandbox manually.
+Sandboxes stay running as long as you need them. When their timeout expires, they can automatically pause to save resources — preserving their full state so you can resume at any time. You can also configure an explicit timeout or shut down a sandbox manually.
 
 <Note>
 Sandboxes can run continuously for up to 24 hours (Pro) or 1 hour (Base). For longer workloads, use [pause and resume](/docs/sandbox/persistence) — pausing resets the runtime window, and your sandbox's full state is preserved indefinitely.
@@ -84,8 +84,8 @@
 //   "templateId": "rki5dems9wqfm4r03t7g",
 //   "name": "base",
 //   "metadata": {},
 //   "startedAt": "2025-03-24T15:37:58.076Z",
 //   "endAt": "2025-03-24T15:42:58.076Z"
 // }
 ```


diff --git a/docs/sandbox/auto-resume.mdx b/docs/sandbox/auto-resume.mdx
@@ -0,0 +1,222 @@
+---
+title: "AutoResume"
+sidebarTitle: AutoResume
+---
+
+<Note>
+`AutoResume` and `pause/resume` persistence are available as **Developer Preview**.
+
+Behavior and limits may change as we iterate. Review [Sandbox persistence limitations](/docs/sandbox/persistence#current-limitations-subject-to-change).
+</Note>
+
+Many workloads don't need a sandbox running all the time, but when they do need it, it should just work, whether it was paused or not.
+
+`AutoResume` handles this automatically: a paused sandbox wakes up when activity arrives, so your code does not have to check or manage sandbox state.
+Configure it through the `lifecycle` object when creating a sandbox.
+
+## Configure lifecycle on create
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from 'e2b'
+
+const sandbox = await Sandbox.create({
+  timeoutMs: 10 * 60 * 1000,
+  lifecycle: {
+    onTimeout: 'pause',
+    autoResume: true, // resume when traffic arrives
+  },
+})
+```
+```python Python
+from e2b import Sandbox
+
+sandbox = Sandbox.create(
+    timeout=10 * 60,
+    lifecycle={
+        "on_timeout": "pause",
+        "auto_resume": True,  # resume when traffic arrives
+    },
+)
+```
+</CodeGroup>
+
+## Lifecycle options
+
+- `onTimeout` / `on_timeout`
+  - `kill` (default): sandbox is terminated when timeout is reached
+  - `pause`: sandbox is paused when timeout is reached
+- `autoResume` / `auto_resume`
+  - `false` (default): paused sandboxes do not auto-resume
+  - `true`: paused sandboxes auto-resume on activity
+  - `true` is valid only when `onTimeout`/`on_timeout` is `pause`
+
+## Behavior summary
+
+- Default behavior is equivalent to `onTimeout: "kill"` with `autoResume: false`.
+- `onTimeout: "pause"` with `autoResume: false` gives auto-pause without auto-resume.
+- `onTimeout: "pause"` with `autoResume: true` gives auto-pause with auto-resume.
+- [`Sandbox.connect()`](/docs/sandbox/connect) can still be used to resume a paused sandbox manually.
+
+If you use `autoResume: false`, resume explicitly with [`Sandbox.connect()`](/docs/sandbox/connect).
+
+## Use cases
+
+### Web and dev/preview servers
+
+Use `onTimeout: "pause"` + `autoResume: true` so inbound traffic can wake a paused sandbox automatically.
+This works for both:
+- Basic web/API servers
+- Dev or preview servers you open occasionally
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from 'e2b'
+
+const sandbox = await Sandbox.create({
+  timeoutMs: 10 * 60 * 1000,
+  lifecycle: {
+    onTimeout: 'pause',
+    autoResume: true,
+  },
+})
+
+// Example: app source already exists in /home/user/app.
+// Replace this command with your API server, Next.js, Vite, etc.
+await sandbox.commands.run(
+  'cd /home/user/app && npm install && npm run dev -- --host 0.0.0.0 --port 3000',
+  { background: true }
+)
+
+const previewHost = sandbox.getHost(3000)
+console.log(`Preview URL: https://${previewHost}`)
+```
+```python Python
+from e2b import Sandbox
+
+sandbox = Sandbox.create(
+    timeout=10 * 60,
+    lifecycle={
+        "on_timeout": "pause",
+        "auto_resume": True,
+    },
+)
+
+# Example: app source already exists in /home/user/app.
+# Replace this command with your API server, Next.js, Vite, etc.
+sandbox.commands.run(
+    "cd /home/user/app && npm install && npm run dev -- --host 0.0.0.0 --port 3000",
+    background=True,
+)
+
+preview_host = sandbox.get_host(3000)
+print(f"Preview URL: https://{preview_host}")
+```
+</CodeGroup>
+
+### Agent/tool execution
+
+For queued tasks or tool calls, create once and keep using the same sandbox handle. If it is paused, it will auto-resume when you run the next command.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from 'e2b'
+
+// One-time setup
+const sandbox = await Sandbox.create({
+  timeoutMs: 5 * 60 * 1000,
+  lifecycle: {
+    onTimeout: 'pause',
+    autoResume: true,
+  },
+})
+
+// Later: called for each agent/tool task
+async function runToolTask(command) {
+  const result = await sandbox.commands.run(command)
+  return result.stdout
+}
+
+console.log(await runToolTask('python -c "print(2 + 2)"'))
+```
+```python Python
+from e2b import Sandbox
+
+# One-time setup
+sandbox = Sandbox.create(
+    timeout=5 * 60,
+    lifecycle={
+        "on_timeout": "pause",
+        "auto_resume": True,
+    },
+)
+
+# Later: called for each agent/tool task
+def run_tool_task(command: str) -> str:
+    result = sandbox.commands.run(command)
+    return result.stdout
+
+print(run_tool_task('python -c "print(2 + 2)"'))
+```
+</CodeGroup>
+
+### Per-user sandboxes
+
+For multi-tenant apps, keep a map of sandbox IDs by user. On each request, connect to the user's existing sandbox (which auto-resumes if paused) or create a new one.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox } from 'e2b'
+
+const userSandboxes = new Map() // userId → Sandbox
+
+async function getSandbox(userId) {
+  let sandbox = userSandboxes.get(userId)
+
+  if (!sandbox) {
+    sandbox = await Sandbox.create({
+      timeoutMs: 5 * 60 * 1000,
+      lifecycle: {
+        onTimeout: 'pause',
+        autoResume: true,
+      },
+    })
+    userSandboxes.set(userId, sandbox)
+  }
+
+  return sandbox
+}
+
+// On each user request (auto-resumes if paused)
+const sandbox = await getSandbox('user-123')
+const result = await sandbox.commands.run('echo "Hello from your sandbox"')
+console.log(result.stdout)
+```
+```python Python
+from e2b import Sandbox
+
+user_sandboxes: dict[str, Sandbox] = {}  # user_id → Sandbox
+
+def get_sandbox(user_id: str) -> Sandbox:
+    if user_id not in user_sandboxes:
+        user_sandboxes[user_id] = Sandbox.create(
+            timeout=5 * 60,
+            lifecycle={
+                "on_timeout": "pause",
+                "auto_resume": True,
+            },
+        )
+
+    return user_sandboxes[user_id]
+
+# On each user request (auto-resumes if paused)
+sandbox = get_sandbox("user-123")
+result = sandbox.commands.run('echo "Hello from your sandbox"')
+print(result.stdout)
+```
+</CodeGroup>
+
+## Cleanup
+Auto-resume is persistent, meaning if your sandbox resumes and later times out again, it will pause again.
+
+If you call `.kill()`, the sandbox is permanently deleted and cannot be resumed.