Skip to content

Commit 58aed17

Browse files
beran-tberan-t
committed
docs: Streamline AutoResume documentation
- Add description to frontmatter - Link to persistence page for full lifecycle context - Merge configuration and cleanup sections - Remove redundant 'Behavior summary' section - Simplify web server example (remove Flask, files.write, sleep, status logging) - Replace with single focused example using python3 -m http.server - Remove unnecessary 'Agent/tool execution' and 'Per-user sandboxes' sections - Explain getHost() method with link to internet-access docs - Reduce page from 256 to 84 lines
1 parent 37b5c49 commit 58aed17

1 file changed

Lines changed: 19 additions & 179 deletions

File tree

‎docs/sandbox/auto-resume.mdx‎

Lines changed: 19 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
---
22
title: "AutoResume"
33
sidebarTitle: AutoResume
4+
description: "Automatically resume paused sandboxes when activity arrives — no manual state management needed."
45
---
56

6-
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.
7+
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.
78

8-
`AutoResume` handles this automatically: a paused sandbox wakes up when activity arrives, so your code does not have to check or manage sandbox state.
9-
Configure it through the `lifecycle` object when creating a sandbox.
9+
`AutoResume` handles this automatically: a paused sandbox wakes up when activity arrives, so your code doesn't have to check or manage sandbox state. AutoResume builds on the sandbox [persistence](/docs/sandbox/persistence) lifecycle.
1010

11-
## Configure lifecycle on create
11+
## Configure AutoResume
12+
13+
Set the `lifecycle` object when creating a sandbox to control what happens on timeout and whether paused sandboxes should auto-resume.
1214

1315
<CodeGroup>
1416
```js JavaScript & TypeScript
@@ -35,7 +37,7 @@ sandbox = Sandbox.create(
3537
```
3638
</CodeGroup>
3739

38-
## Lifecycle options
40+
### Lifecycle options
3941

4042
- `onTimeout` / `on_timeout`
4143
- `kill` (default): sandbox is terminated when timeout is reached
@@ -45,117 +47,20 @@ sandbox = Sandbox.create(
4547
- `true`: paused sandboxes auto-resume on activity
4648
- `true` is valid only when `onTimeout`/`on_timeout` is `pause`
4749

48-
## Behavior summary
49-
50-
- Default behavior is equivalent to `onTimeout: "kill"` with `autoResume: false`.
51-
- `onTimeout: "pause"` with `autoResume: false` gives auto-pause without auto-resume.
52-
- `onTimeout: "pause"` with `autoResume: true` gives auto-pause with auto-resume.
53-
- [`Sandbox.connect()`](/docs/sandbox/connect) can still be used to resume a paused sandbox manually.
54-
55-
If you use `autoResume: false`, resume explicitly with [`Sandbox.connect()`](/docs/sandbox/connect).
56-
57-
## Use cases
58-
59-
### Web and dev/preview servers
60-
61-
Use `onTimeout: "pause"` + `autoResume: true` so inbound traffic can wake a paused sandbox automatically.
62-
This works for both:
63-
- Basic web/API servers
64-
- Dev or preview servers you open occasionally
65-
66-
<CodeGroup>
67-
```js JavaScript & TypeScript
68-
import { Sandbox } from 'e2b'
69-
70-
const sandbox = await Sandbox.create({
71-
timeoutMs: 10 * 60 * 1000,
72-
lifecycle: {
73-
onTimeout: 'pause',
74-
autoResume: true,
75-
},
76-
})
77-
78-
await sandbox.commands.run(
79-
`python3 -m pip -q install 'flask>=2.2'`
80-
)
81-
82-
await sandbox.files.write(
83-
'/home/user/app.py',
84-
[
85-
'from flask import Flask',
86-
'app = Flask(__name__)',
87-
'@app.route("/")',
88-
'def hello():',
89-
' return "Hello, World!"',
90-
'app.run(host="0.0.0.0", port=3000)',
91-
'',
92-
].join('\n')
93-
)
94-
95-
await sandbox.commands.run(
96-
'python3 -u /home/user/app.py > /home/user/flask.log 2>&1',
97-
{ background: true }
98-
)
99-
100-
await new Promise((resolve) => setTimeout(resolve, 1000))
101-
102-
const previewHost = sandbox.getHost(3000)
103-
console.log(`Preview URL: https://${previewHost}`)
104-
105-
console.log(`Status before pause: ${(await sandbox.getInfo()).state}`)
106-
await sandbox.pause()
107-
console.log(`Status after pause: ${(await sandbox.getInfo()).state}`)
108-
```
109-
```python Python
110-
import time
111-
112-
from e2b import Sandbox
113-
114-
sandbox = Sandbox.create(
115-
timeout=10 * 60,
116-
lifecycle={
117-
"on_timeout": "pause",
118-
"auto_resume": True,
119-
},
120-
)
121-
122-
sandbox.commands.run("python3 -m pip -q install 'flask>=2.2'")
50+
AutoResume is persistent — if a sandbox resumes and later times out again, it will pause again automatically. To permanently delete a sandbox, call `.kill()`. A killed sandbox cannot be resumed.
12351

124-
sandbox.files.write(
125-
"/home/user/app.py",
126-
'from flask import Flask\n'
127-
'app = Flask(__name__)\n'
128-
'@app.route("/")\n'
129-
'def hello():\n'
130-
' return "Hello, World!"\n'
131-
'app.run(host="0.0.0.0", port=3000)\n'
132-
)
133-
134-
sandbox.commands.run(
135-
"python3 -u /home/user/app.py > /home/user/flask.log 2>&1",
136-
background=True,
137-
)
138-
139-
time.sleep(1)
52+
If `autoResume` is `false`, you can still resume a paused sandbox manually with [`Sandbox.connect()`](/docs/sandbox/connect).
14053

141-
preview_host = sandbox.get_host(3000)
142-
print(f"Preview URL: https://{preview_host}")
54+
## Example: Web server with AutoResume
14355

144-
print(f"Status before pause: {sandbox.get_info().state}")
145-
sandbox.pause()
146-
print(f"Status after pause: {sandbox.get_info().state}")
147-
```
148-
</CodeGroup>
56+
AutoResume is especially useful for web servers and preview environments. When an HTTP request arrives at a paused sandbox, the sandbox wakes up automatically to handle it.
14957

150-
### Agent/tool execution
151-
152-
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.
58+
The following example starts a simple HTTP server and retrieves its public URL. Use [`getHost()`](/docs/sandbox/internet-access#sandbox-public-url) / `get_host()` to get the sandbox's publicly accessible hostname for a given port.
15359

15460
<CodeGroup>
15561
```js JavaScript & TypeScript
15662
import { Sandbox } from 'e2b'
15763

158-
// One-time setup
15964
const sandbox = await Sandbox.create({
16065
timeoutMs: 5 * 60 * 1000,
16166
lifecycle: {
@@ -164,18 +69,14 @@ const sandbox = await Sandbox.create({
16469
},
16570
})
16671

167-
// Later: called for each agent/tool task
168-
async function runToolTask(command) {
169-
const result = await sandbox.commands.run(command)
170-
return result.stdout
171-
}
72+
await sandbox.commands.run('python3 -m http.server 3000', { background: true })
17273

173-
console.log(await runToolTask('python -c "print(2 + 2)"'))
74+
const host = sandbox.getHost(3000)
75+
console.log(`Preview URL: https://${host}`)
17476
```
17577
```python Python
17678
from e2b import Sandbox
17779

178-
# One-time setup
17980
sandbox = Sandbox.create(
18081
timeout=5 * 60,
18182
lifecycle={
@@ -184,72 +85,11 @@ sandbox = Sandbox.create(
18485
},
18586
)
18687

187-
# Later: called for each agent/tool task
188-
def run_tool_task(command: str) -> str:
189-
result = sandbox.commands.run(command)
190-
return result.stdout
191-
192-
print(run_tool_task('python -c "print(2 + 2)"'))
193-
```
194-
</CodeGroup>
195-
196-
### Per-user sandboxes
197-
198-
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.
199-
200-
<CodeGroup>
201-
```js JavaScript & TypeScript
202-
import { Sandbox } from 'e2b'
88+
sandbox.commands.run("python3 -m http.server 3000", background=True)
20389

204-
const userSandboxes = new Map() // userId → Sandbox
205-
206-
async function getSandbox(userId) {
207-
let sandbox = userSandboxes.get(userId)
208-
209-
if (!sandbox) {
210-
sandbox = await Sandbox.create({
211-
timeoutMs: 5 * 60 * 1000,
212-
lifecycle: {
213-
onTimeout: 'pause',
214-
autoResume: true,
215-
},
216-
})
217-
userSandboxes.set(userId, sandbox)
218-
}
219-
220-
return sandbox
221-
}
222-
223-
// On each user request (auto-resumes if paused)
224-
const sandbox = await getSandbox('user-123')
225-
const result = await sandbox.commands.run('echo "Hello from your sandbox"')
226-
console.log(result.stdout)
227-
```
228-
```python Python
229-
from e2b import Sandbox
230-
231-
user_sandboxes: dict[str, Sandbox] = {} # user_id → Sandbox
232-
233-
def get_sandbox(user_id: str) -> Sandbox:
234-
if user_id not in user_sandboxes:
235-
user_sandboxes[user_id] = Sandbox.create(
236-
timeout=5 * 60,
237-
lifecycle={
238-
"on_timeout": "pause",
239-
"auto_resume": True,
240-
},
241-
)
242-
243-
return user_sandboxes[user_id]
244-
245-
# On each user request (auto-resumes if paused)
246-
sandbox = get_sandbox("user-123")
247-
result = sandbox.commands.run('echo "Hello from your sandbox"')
248-
print(result.stdout)
90+
host = sandbox.get_host(3000)
91+
print(f"Preview URL: https://{host}")
24992
```
25093
</CodeGroup>
25194

252-
## Cleanup
253-
Auto-resume is persistent, meaning if your sandbox resumes and later times out again, it will pause again.
254-
255-
If you call `.kill()`, the sandbox is permanently deleted and cannot be resumed.
95+
Once the sandbox times out and pauses, any request to the preview URL will automatically resume it.

0 commit comments

Comments
 (0)