add docs for keepAlive flag

Author: whoiskatrin

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

@@ -13,6 +13,44 @@ Create isolated execution contexts within a sandbox. Each session maintains its
 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.
 :::
 
+## Sandbox options
+
+When creating a sandbox with `getSandbox()`, you can configure its lifecycle behavior:
+
+```ts
+import { getSandbox } from '@cloudflare/sandbox';
+
+const sandbox = getSandbox(binding, sandboxId, options?: SandboxOptions);
+```
+
+**Available options**:
+
+- `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`
+
+<TypeScriptExample>
+```
+// For long-running processes that need the container to stay alive
+const sandbox = getSandbox(env.Sandbox, 'user-123', {
+  keepAlive: true
+});
+
+// Run your long-running process
+await sandbox.startProcess('python long_running_script.py');
+
+// Important: Must explicitly destroy when done
+try {
+// Your work here
+} finally {
+await sandbox.destroy(); // Required to prevent resource leaks
+}
+
+````
+</TypeScriptExample>
+
+:::caution[Resource management with keepAlive]
+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.
+:::
+
 ## Methods
 
 ### `createSession()`
@@ -41,15 +79,15 @@ const prodSession = await sandbox.createSession({
 });
 
 const testSession = await sandbox.createSession({
-  id: 'test',
-  env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
-  cwd: '/workspace/test'
+id: 'test',
+env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
+cwd: '/workspace/test'
 });
 
 // Run in parallel
 const [prodResult, testResult] = await Promise.all([
-  prodSession.exec('npm run build'),
-  testSession.exec('npm run build')
+prodSession.exec('npm run build'),
+testSession.exec('npm run build')
 ]);
 ```
 </TypeScriptExample>
@@ -101,9 +139,9 @@ const sandbox = getSandbox(env.Sandbox, 'user-123');
 
 // Set environment variables first
 await sandbox.setEnvVars({
-  API_KEY: env.OPENAI_API_KEY,
-  DATABASE_URL: env.DATABASE_URL,
-  NODE_ENV: 'production'
+API_KEY: env.OPENAI_API_KEY,
+DATABASE_URL: env.DATABASE_URL,
+NODE_ENV: 'production'
 });
 
 // Now commands can access these variables
@@ -120,21 +158,23 @@ await sandbox.destroy(): Promise<void>
 ```
 
 :::note
-Containers automatically sleep after 3 minutes of inactivity, but still count toward account limits. Use `destroy()` to immediately free up resources.
+Containers automatically sleep after 10 minutes of inactivity, but still count toward account limits. Use `destroy()` to immediately free up resources.
+
+**Important**: When using `keepAlive: true`, containers will not automatically timeout, so calling `destroy()` is **required** to prevent resource leaks.
 :::
 
 <TypeScriptExample>
 ```
 async function executeCode(code: string): Promise<string> {
   const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);
 
-  try {
-    await sandbox.writeFile('/tmp/code.py', code);
-    const result = await sandbox.exec('python /tmp/code.py');
-    return result.stdout;
-  } finally {
-    await sandbox.destroy();
-  }
+try {
+await sandbox.writeFile('/tmp/code.py', code);
+const result = await sandbox.exec('python /tmp/code.py');
+return result.stdout;
+} finally {
+await sandbox.destroy();
+}
 }
 ```
 </TypeScriptExample>
@@ -143,13 +183,15 @@ async function executeCode(code: string): Promise<string> {
 
 The `ExecutionSession` object has all sandbox methods bound to the specific session:
 
-**Commands**: [`exec()`](/sandbox/api/commands/#exec), [`execStream()`](/sandbox/api/commands/#execstream)  
-**Processes**: [`startProcess()`](/sandbox/api/commands/#startprocess), [`listProcesses()`](/sandbox/api/commands/#listprocesses), [`killProcess()`](/sandbox/api/commands/#killprocess), [`killAllProcesses()`](/sandbox/api/commands/#killallprocesses), [`getProcessLogs()`](/sandbox/api/commands/#getprocesslogs), [`streamProcessLogs()`](/sandbox/api/commands/#streamprocesslogs)  
-**Files**: [`writeFile()`](/sandbox/api/files/#writefile), [`readFile()`](/sandbox/api/files/#readfile), [`mkdir()`](/sandbox/api/files/#mkdir), [`deleteFile()`](/sandbox/api/files/#deletefile), [`renameFile()`](/sandbox/api/files/#renamefile), [`moveFile()`](/sandbox/api/files/#movefile), [`gitCheckout()`](/sandbox/api/files/#gitcheckout)  
-**Environment**: [`setEnvVars()`](/sandbox/api/sessions/#setenvvars)  
+**Commands**: [`exec()`](/sandbox/api/commands/#exec), [`execStream()`](/sandbox/api/commands/#execstream)
+**Processes**: [`startProcess()`](/sandbox/api/commands/#startprocess), [`listProcesses()`](/sandbox/api/commands/#listprocesses), [`killProcess()`](/sandbox/api/commands/#killprocess), [`killAllProcesses()`](/sandbox/api/commands/#killallprocesses), [`getProcessLogs()`](/sandbox/api/commands/#getprocesslogs), [`streamProcessLogs()`](/sandbox/api/commands/#streamprocesslogs)
+**Files**: [`writeFile()`](/sandbox/api/files/#writefile), [`readFile()`](/sandbox/api/files/#readfile), [`mkdir()`](/sandbox/api/files/#mkdir), [`deleteFile()`](/sandbox/api/files/#deletefile), [`renameFile()`](/sandbox/api/files/#renamefile), [`moveFile()`](/sandbox/api/files/#movefile), [`gitCheckout()`](/sandbox/api/files/#gitcheckout)
+**Environment**: [`setEnvVars()`](/sandbox/api/sessions/#setenvvars)
 **Code Interpreter**: [`createCodeContext()`](/sandbox/api/interpreter/#createcodecontext), [`runCode()`](/sandbox/api/interpreter/#runcode), [`listCodeContexts()`](/sandbox/api/interpreter/#listcodecontexts), [`deleteCodeContext()`](/sandbox/api/interpreter/#deletecodecontext)
 
 ## Related resources
 
 - [Session management concept](/sandbox/concepts/sessions/) - How sessions work
 - [Commands API](/sandbox/api/commands/) - Execute commands
+```
+````

src/content/docs/sandbox/concepts/sandboxes.mdx

@@ -20,19 +20,17 @@ A sandbox is an isolated execution environment where your code runs. Each sandbo
 A sandbox is created the first time you reference its ID:
 
 ```typescript
-const sandbox = getSandbox(env.Sandbox, 'user-123');
+const sandbox = getSandbox(env.Sandbox, "user-123");
 await sandbox.exec('echo "Hello"'); // First request creates sandbox
 ```
 
-**Duration**: 100-300ms (cold start) or \<10ms (if warm)
-
 ### Active
 
 The sandbox container is running and processing requests. All state remains available: files, running processes, shell sessions, and environment variables.
 
 ### Idle
 
-After a period of inactivity, the container stops to free resources. When the next request arrives, a fresh container starts. All previous state is lost and the environment resets to its initial state.
+After a period of inactivity (10 minutes by default), the container stops to free resources. When the next request arrives, a fresh container starts. All previous state is lost and the environment resets to its initial state.
 
 ### Destruction
 
@@ -48,12 +46,14 @@ await sandbox.destroy();
 Sandbox state exists only while the container is active. Understanding this is critical for building reliable applications.
 
 **While the container is active** (typically minutes to hours of activity):
+
 - Files written to `/workspace`, `/tmp`, `/home` remain available
 - Background processes continue running
 - Shell sessions maintain their working directory and environment
 - Code interpreter contexts retain variables and imports
 
 **When the container stops** (due to inactivity or explicit destruction):
+
 - All files are deleted
 - All processes terminate
 - All shell state resets
@@ -95,6 +95,7 @@ Idempotent operations with clear task-to-sandbox mapping. Good for builds, pipel
 The first request to a sandbox determines its geographic location. Subsequent requests route to the same location.
 
 **For global apps**:
+
 - Option 1: Multiple sandboxes per user with region suffix (`user-123-us`, `user-123-eu`)
 - Option 2: Single sandbox per user (simpler, but some users see higher latency)
 
@@ -104,10 +105,10 @@ The first request to a sandbox determines its geographic location. Subsequent re
 
 ```typescript
 try {
-  const sandbox = getSandbox(env.Sandbox, sessionId);
-  await sandbox.exec('npm run build');
+	const sandbox = getSandbox(env.Sandbox, sessionId);
+	await sandbox.exec("npm run build");
 } finally {
-  await sandbox.destroy(); // Clean up temporary sandboxes
+	await sandbox.destroy(); // Clean up temporary sandboxes
 }
 ```
 
@@ -121,13 +122,13 @@ Containers restart after inactivity or failures. Design your application to hand
 
 ```typescript
 // Check if required files exist before using them
-const files = await sandbox.listFiles('/workspace');
-if (!files.includes('data.json')) {
-  // Reinitialize: container restarted and lost previous state
-  await sandbox.writeFile('/workspace/data.json', initialData);
+const files = await sandbox.listFiles("/workspace");
+if (!files.includes("data.json")) {
+	// Reinitialize: container restarted and lost previous state
+	await sandbox.writeFile("/workspace/data.json", initialData);
 }
 
-await sandbox.exec('python process.py');
+await sandbox.exec("python process.py");
 ```
 
 ## Best practices

src/content/docs/sandbox/guides/background-processes.mdx

@@ -159,12 +159,57 @@ console.log('All services running');
 ```
 </TypeScriptExample>
 
+## Keep containers alive for long-running processes
+
+By default, containers automatically shut down after 3 minutes of inactivity. For long-running processes that may have idle periods (like CI/CD pipelines, batch jobs, or monitoring tasks), use the `keepAlive` option:
+
+<TypeScriptExample>
+```
+import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Enable keepAlive for long-running processes
+    const sandbox = getSandbox(env.Sandbox, 'build-job-123', {
+      keepAlive: true
+    });
+
+    try {
+      // Start a long-running build process
+      const build = await sandbox.startProcess('npm run build:production');
+
+      // Monitor progress
+      const logs = await sandbox.streamProcessLogs(build.id);
+
+      // Process can run indefinitely without container shutdown
+      for await (const log of parseSSEStream<LogEvent>(logs)) {
+        console.log(log.data);
+        if (log.data.includes('Build complete')) {
+          break;
+        }
+      }
+
+      return new Response('Build completed');
+    } finally {
+      // Important: Must explicitly destroy when done
+      await sandbox.destroy();
+    }
+  }
+};
+```
+</TypeScriptExample>
+
+:::caution[Always destroy with keepAlive]
+When using `keepAlive: true`, containers will not automatically timeout. You **must** call `sandbox.destroy()` when finished to prevent resource leaks and avoid counting containers toward your account limits indefinitely.
+:::
+
 ## Best practices
 
 - **Wait for readiness** - Stream logs to detect when services are ready
 - **Clean up** - Always stop processes when done
 - **Handle failures** - Monitor logs for errors and restart if needed
 - **Use try/finally** - Ensure cleanup happens even on errors
+- **Use keepAlive for long-running tasks** - Prevent container shutdown during processes with idle periods
 
 ## Troubleshooting
 
@@ -199,6 +244,7 @@ const server = await sandbox.startProcess('node server.js');
 ## Related resources
 
 - [Commands API reference](/sandbox/api/commands/) - Complete process management API
+- [Sessions API reference](/sandbox/api/sessions/) - Container lifecycle and keepAlive option
 - [Execute commands guide](/sandbox/guides/execute-commands/) - One-time command execution
 - [Expose services guide](/sandbox/guides/expose-services/) - Make processes accessible
 - [Streaming output guide](/sandbox/guides/streaming-output/) - Monitor process output