Skip to content

Commit 410091a

Browse files
whoiskatrinwhoiskatrin
committed
update docs
1 parent e74563f commit 410091a

File tree

4 files changed

+115
-98
lines changed

4 files changed

+115
-98
lines changed

‎src/content/docs/sandbox/api/sessions.mdx‎

Lines changed: 18 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -13,42 +13,8 @@ Create isolated execution contexts within a sandbox. Each session maintains its
1313
Every sandbox has a default session that automatically maintains shell state. Create additional sessions when you need isolated shell contexts for different environments or parallel workflows.
1414
:::
1515

16-
## Sandbox options
17-
18-
When creating a sandbox with `getSandbox()`, you can configure its lifecycle behavior:
19-
20-
```ts
21-
import { getSandbox } from '@cloudflare/sandbox';
22-
23-
const sandbox = getSandbox(binding, sandboxId, options?: SandboxOptions);
24-
```
25-
26-
**Available options**:
27-
28-
- `keepAlive` (boolean) - Keep the container alive indefinitely by preventing automatic shutdown. When `true`, the container will never auto-timeout and must be explicitly destroyed using `destroy()`. Default: `false`
29-
30-
<TypeScriptExample>
31-
```
32-
// For long-running processes that need the container to stay alive
33-
const sandbox = getSandbox(env.Sandbox, 'user-123', {
34-
keepAlive: true
35-
});
36-
37-
// Run your long-running process
38-
await sandbox.startProcess('python long_running_script.py');
39-
40-
// Important: Must explicitly destroy when done
41-
try {
42-
// Your work here
43-
} finally {
44-
await sandbox.destroy(); // Required to prevent resource leaks
45-
}
46-
47-
````
48-
</TypeScriptExample>
49-
50-
:::caution[Resource management with keepAlive]
51-
When `keepAlive: true` is set, containers will not automatically timeout and must be explicitly destroyed using `destroy()` to prevent resource leaks and avoid counting toward account limits indefinitely.
16+
:::note
17+
For sandbox-level configuration options like `keepAlive`, see the [Sandbox options configuration](/sandbox/configuration/sandbox-options/).
5218
:::
5319

5420
## Methods
@@ -79,15 +45,15 @@ const prodSession = await sandbox.createSession({
7945
});
8046
8147
const testSession = await sandbox.createSession({
82-
id: 'test',
83-
env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
84-
cwd: '/workspace/test'
48+
id: 'test',
49+
env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
50+
cwd: '/workspace/test'
8551
});
8652
8753
// Run in parallel
8854
const [prodResult, testResult] = await Promise.all([
89-
prodSession.exec('npm run build'),
90-
testSession.exec('npm run build')
55+
prodSession.exec('npm run build'),
56+
testSession.exec('npm run build')
9157
]);
9258
```
9359
</TypeScriptExample>
@@ -139,9 +105,9 @@ const sandbox = getSandbox(env.Sandbox, 'user-123');
139105
140106
// Set environment variables first
141107
await sandbox.setEnvVars({
142-
API_KEY: env.OPENAI_API_KEY,
143-
DATABASE_URL: env.DATABASE_URL,
144-
NODE_ENV: 'production'
108+
API_KEY: env.OPENAI_API_KEY,
109+
DATABASE_URL: env.DATABASE_URL,
110+
NODE_ENV: 'production'
145111
});
146112
147113
// Now commands can access these variables
@@ -160,21 +126,21 @@ await sandbox.destroy(): Promise<void>
160126
:::note
161127
Containers automatically sleep after 10 minutes of inactivity, but still count toward account limits. Use `destroy()` to immediately free up resources.
162128

163-
**Important**: When using `keepAlive: true`, containers will not automatically timeout, so calling `destroy()` is **required** to prevent resource leaks.
129+
**Important**: When using [`keepAlive: true`](/sandbox/configuration/sandbox-options/#keepalive), containers will not automatically timeout, so calling `destroy()` is **required** to prevent containers running indefinitely.
164130
:::
165131

166132
<TypeScriptExample>
167133
```
168134
async function executeCode(code: string): Promise<string> {
169135
const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);
170136
171-
try {
172-
await sandbox.writeFile('/tmp/code.py', code);
173-
const result = await sandbox.exec('python /tmp/code.py');
174-
return result.stdout;
175-
} finally {
176-
await sandbox.destroy();
177-
}
137+
try {
138+
await sandbox.writeFile('/tmp/code.py', code);
139+
const result = await sandbox.exec('python /tmp/code.py');
140+
return result.stdout;
141+
} finally {
142+
await sandbox.destroy();
143+
}
178144
}
179145
```
180146
</TypeScriptExample>
@@ -193,5 +159,3 @@ The `ExecutionSession` object has all sandbox methods bound to the specific sess
193159

194160
- [Session management concept](/sandbox/concepts/sessions/) - How sessions work
195161
- [Commands API](/sandbox/api/commands/) - Execute commands
196-
```
197-
````

‎src/content/docs/sandbox/configuration/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,14 @@ Configure your Sandbox SDK deployment with Wrangler, customize container images,
3737
Pass configuration and secrets to your sandboxes using environment variables.
3838
</LinkTitleCard>
3939

40+
<LinkTitleCard
41+
title="Sandbox options"
42+
href="/sandbox/configuration/sandbox-options/"
43+
icon="setting"
44+
>
45+
Configure sandbox behavior with options like keepAlive for long-running processes.
46+
</LinkTitleCard>
47+
4048
</CardGrid>
4149

4250
## Related resources

‎src/content/docs/sandbox/configuration/sandbox-options.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Sandbox options
3+
pcx_content_type: configuration
4+
sidebar:
5+
order: 4
6+
---
7+
8+
import { TypeScriptExample } from "~/components";
9+
10+
Configure sandbox behavior by passing options when creating a sandbox instance with `getSandbox()`.
11+
12+
## Available options
13+
14+
```ts
15+
import { getSandbox } from '@cloudflare/sandbox';
16+
17+
const sandbox = getSandbox(binding, sandboxId, options?: SandboxOptions);
18+
```
19+
20+
### keepAlive
21+
22+
**Type**: `boolean`
23+
**Default**: `false`
24+
25+
Keep the container alive indefinitely by preventing automatic shutdown. When `true`, the container will never auto-timeout and must be explicitly destroyed using `destroy()`.
26+
27+
<TypeScriptExample>
28+
```
29+
// For long-running processes that need the container to stay alive
30+
const sandbox = getSandbox(env.Sandbox, 'user-123', {
31+
keepAlive: true
32+
});
33+
34+
// Run your long-running process
35+
await sandbox.startProcess('python long_running_script.py');
36+
37+
// Important: Must explicitly destroy when done
38+
try {
39+
// Your work here
40+
} finally {
41+
await sandbox.destroy(); // Required to prevent containers running indefinitely
42+
}
43+
```
44+
</TypeScriptExample>
45+
46+
:::caution[Resource management with keepAlive]
47+
When `keepAlive: true` is set, containers will not automatically timeout and must be explicitly destroyed using `destroy()` to prevent containers running indefinitely and counting toward your account limits.
48+
:::
49+
50+
## When to use keepAlive
51+
52+
Use `keepAlive: true` for:
53+
54+
- **Long-running builds** - CI/CD pipelines that may have idle periods between steps
55+
- **Batch processing** - Jobs that process data in waves with gaps between batches
56+
- **Monitoring tasks** - Processes that periodically check external services
57+
- **Interactive sessions** - User-driven workflows where the container should remain available
58+
59+
By default, containers automatically shut down after 10 minutes of inactivity. The `keepAlive` option prevents this automatic shutdown.
60+
61+
## Related resources
62+
63+
- [Background processes guide](/sandbox/guides/background-processes/) - Using keepAlive with long-running processes
64+
- [Sessions API reference](/sandbox/api/sessions/) - Container lifecycle management
65+
- [Sandboxes concept](/sandbox/concepts/sandboxes/) - Understanding sandbox lifecycle

0 commit comments

Comments
 (0)