AutoResume Docs

docs.json

@@ -100,6 +100,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",

docs/agents/amp.mdx

@@ -299,7 +299,7 @@ python build.py
 
 <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

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
 
@@ -451,7 +451,7 @@
     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

docs/agents/codex.mdx

@@ -246,7 +246,7 @@
 
 ## Image input
 
 Pass screenshots or design mockups with `--image` to give Codex visual context alongside the prompt.
 
 <CodeGroup>
 ```typescript JavaScript & TypeScript
@@ -355,7 +355,7 @@
 
 <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

docs/agents/openclaw.mdx

@@ -386,9 +386,9 @@ sandbox.kill()
 
 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
@@ -499,7 +499,7 @@ python build.py
 
 <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

docs/agents/opencode.mdx

@@ -277,7 +277,7 @@ python build.py
 
 <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

docs/billing.mdx

@@ -93,7 +93,7 @@ Check your usage and costs in the [dashboard usage tab](https://e2b.dev/dashboar
 
   <Accordion title="How do I optimize costs?">
     - **Always kill sandboxes when done** - Use `sbx.kill()` to stop billing immediately
-    - **Enable autopause** - Automatically pause sandboxes after a period of inactivity to stop billing while preserving state
+    - **Enable auto-pause (Developer Preview)** - Automatically pause sandboxes after inactivity to stop billing while preserving state
     - **Allocate only what you need** - Start with default resources (2 vCPU, 1 GB RAM) and increase only if necessary
     - **Implement automatic timeouts** - Set max session lengths to prevent forgotten sandboxes from running
     - **Monitor actively running sandboxes** - Use the [CLI](/docs/cli/list-sandboxes) or [dashboard](https://e2b.dev/dashboard?tab=usage) to track active sandboxes

docs/sandbox.mdx

@@ -3,16 +3,19 @@ title: "Sandbox lifecycle"
 sidebarTitle: Lifecycle
 ---
 
-When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter.
-After the time passes, the sandbox will be automatically shutdown.
-
-<Warning>
-The maximum time sandbox can be kept running without being paused is 
-- 24 hours on the Pro Tier
+When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter.
+After the time passes, the sandbox will be automatically shutdown.
+
+For timeout lifecycle behavior like pausing and auto-resume policies on create, see [AutoResume](/docs/sandbox/auto-resume).
+Pause/resume persistence and auto-resume are currently in **Developer Preview**.
+
+<Warning>
+The maximum time sandbox can be kept running without being paused is 
+- 24 hours on the Pro Tier
 - 1 hour on the Base Tier
 
-For more details, please refer to [sandbox persistance page](/docs/sandbox/persistence#limitations-while-in-beta).
-</Warning>
+For more details, please refer to the [sandbox persistence page](/docs/sandbox/persistence#current-limitations-subject-to-change).
+</Warning>
 
 <CodeGroup>
 ```js JavaScript & TypeScript highlight={6}

docs/sandbox/auto-resume.mdx

@@ -0,0 +1,221 @@
+---
+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 traffic arrives, so your code never has 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 traffic
+  - `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.
+
+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.