Fix sandbox configuration information

ghostwriternr · ghostwriternr · commit 45bfcec3ec03 · 2025-10-21T13:35:32.000+01:00
diff --git a/src/content/docs/sandbox/concepts/containers.mdx b/src/content/docs/sandbox/concepts/containers.mdx
@@ -5,32 +5,11 @@ sidebar:
   order: 3
 ---
 
-Each sandbox runs in an isolated Linux container based on Ubuntu 22.04.
+Each sandbox runs in an isolated Linux container with Python, Node.js, and common development tools pre-installed. For a complete list of pre-installed software and how to customize the container image, see [Dockerfile reference](/sandbox/configuration/dockerfile/).
 
-## Pre-installed software
+## Runtime software installation
 
-The base container comes with essential development tools:
-
-**Languages and runtimes**:
-- Python 3.11 with pip and venv
-- Node.js 20 LTS with npm
-- Bun 1.x (JavaScript/TypeScript runtime)
-
-**Python packages**:
-- matplotlib - Plotting and visualization
-- numpy - Numerical computing
-- pandas - Data analysis
-- ipython - Interactive Python shell
-
-**System utilities**:
-- curl, wget - HTTP clients
-- git - Version control
-- jq - JSON processor
-- zip, unzip - Archive tools
-- file - File type identification
-- procps - Process utilities
-
-Install additional software at runtime or [customize the base image](/sandbox/configuration/dockerfile/):
+Install additional software at runtime using standard package managers:
 
 ```bash
 # Python packages
diff --git a/src/content/docs/sandbox/configuration/dockerfile.mdx b/src/content/docs/sandbox/configuration/dockerfile.mdx
@@ -22,11 +22,11 @@ Always match the Docker image version to your npm package version. If you're usi
 **What's included:**
 
 - Ubuntu 22.04 LTS base
-- Python 3.11+ with pip
-- Bun (JavaScript/TypeScript runtime)
-- Git, curl, wget, and common CLI tools
-- Pre-installed Python packages: pandas, numpy, matplotlib
-- System libraries for most common use cases
+- Python 3.11 with pip and venv
+- Node.js 20 LTS with npm
+- Bun 1.x (JavaScript/TypeScript runtime)
+- Pre-installed Python packages: matplotlib, numpy, pandas, ipython
+- System utilities: curl, wget, git, jq, zip, unzip, file, procps, ca-certificates
 
 ## Creating a custom image
 
@@ -57,8 +57,8 @@ Update `wrangler.jsonc` to reference your Dockerfile:
 {
 	"containers": [
 		{
-			"binding": "CONTAINER",
-			"dockerfile": "./Dockerfile",
+			"class_name": "Sandbox",
+			"image": "./Dockerfile",
 		},
 	],
 }
diff --git a/src/content/docs/sandbox/configuration/environment-variables.mdx b/src/content/docs/sandbox/configuration/environment-variables.mdx
@@ -7,185 +7,165 @@ sidebar:
 
 Pass configuration, secrets, and runtime settings to your sandboxes using environment variables.
 
-### Command and process variables
+## Three ways to set environment variables
 
-Pass environment variables when executing commands or starting processes:
+The Sandbox SDK provides three methods for setting environment variables, each suited for different use cases:
+
+### 1. Sandbox-level with setEnvVars()
+
+Set environment variables globally for all commands in the sandbox:
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, "my-sandbox");
+
+// Set once, available for all subsequent commands
+await sandbox.setEnvVars({
+	DATABASE_URL: env.DATABASE_URL,
+	API_KEY: env.API_KEY,
+});
+
+await sandbox.exec("python migrate.py"); // Has DATABASE_URL and API_KEY
+await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY
+```
+
+**Use when:** You need the same environment variables for multiple commands.
+
+### 2. Per-command with exec() options
+
+Pass environment variables for a specific command:
 
 ```typescript
-// Commands
 await sandbox.exec("node app.js", {
 	env: {
 		NODE_ENV: "production",
-		API_KEY: env.API_KEY, // Pass from Worker env
 		PORT: "3000",
 	},
 });
 
-// Background processes (same syntax)
+// Also works with startProcess()
 await sandbox.startProcess("python server.py", {
 	env: {
 		DATABASE_URL: env.DATABASE_URL,
-		SECRET_KEY: env.SECRET_KEY,
 	},
 });
 ```
 
-### Session-level variables
+**Use when:** You need different environment variables for different commands, or want to override sandbox-level variables.
 
-Set environment variables for all commands in a session:
+### 3. Session-level with createSession()
 
-```typescript
-const session = await sandbox.createSession();
+Create an isolated session with its own environment variables:
 
-await session.setEnvVars({
-	DATABASE_URL: env.DATABASE_URL,
-	SECRET_KEY: env.SECRET_KEY,
+```typescript
+const session = await sandbox.createSession({
+	env: {
+		DATABASE_URL: env.DATABASE_URL,
+		SECRET_KEY: env.SECRET_KEY,
+	},
 });
 
 // All commands in this session have these vars
 await session.exec("python migrate.py");
 await session.exec("python seed.py");
 ```
 
+**Use when:** You need isolated execution contexts with different environment variables running concurrently.
+
 ## Common patterns
 
 ### Pass Worker secrets to sandbox
 
-Securely pass secrets from Worker environment:
+Securely pass secrets from your Worker to the sandbox. First, set secrets using Wrangler:
+
+```bash
+wrangler secret put OPENAI_API_KEY
+wrangler secret put DATABASE_URL
+```
+
+Then pass them to your sandbox:
 
 ```typescript
 interface Env {
 	Sandbox: DurableObjectNamespace;
-	OPENAI_API_KEY: string; // Set with `wrangler secret put`
+	OPENAI_API_KEY: string;
 	DATABASE_URL: string;
 }
 
 export default {
 	async fetch(request: Request, env: Env): Promise<Response> {
 		const sandbox = getSandbox(env.Sandbox, "user-sandbox");
 
-		const result = await sandbox.exec("python analyze.py", {
+		// Option 1: Set globally for all commands
+		await sandbox.setEnvVars({
+			OPENAI_API_KEY: env.OPENAI_API_KEY,
+			DATABASE_URL: env.DATABASE_URL,
+		});
+		await sandbox.exec("python analyze.py");
+
+		// Option 2: Pass per-command
+		await sandbox.exec("python analyze.py", {
 			env: {
 				OPENAI_API_KEY: env.OPENAI_API_KEY,
-				DATABASE_URL: env.DATABASE_URL,
 			},
 		});
 
-		return Response.json({ result });
+		return Response.json({ success: true });
 	},
 };
 ```
 
-### Default values with spreading
-
-Combine default and command-specific variables:
+### Combine default and specific variables
 
 ```typescript
-const defaults = {
-	NODE_ENV: env.ENVIRONMENT || "production",
-	LOG_LEVEL: "info",
-	TZ: "UTC",
-};
+const defaults = { NODE_ENV: "production", LOG_LEVEL: "info" };
 
 await sandbox.exec("npm start", {
-	env: {
-		...defaults,
-		PORT: "3000", // Command-specific override
-		API_KEY: env.API_KEY,
-	},
-});
-```
-
-## Environment variable precedence
-
-When the same variable is set at multiple levels:
-
-1. **Command-level** (highest) - Passed to `exec()` or `startProcess()`
-2. **Session-level** - Set with `setEnvVars()`
-3. **Container default** - Built into the Docker image
-4. **System default** (lowest) - Operating system defaults
-
-Example:
-
-```typescript
-// In Dockerfile: ENV NODE_ENV=development
-// In session: await sandbox.setEnvVars({ NODE_ENV: 'staging' });
-
-// In command (overrides all):
-await sandbox.exec("node app.js", {
-	env: { NODE_ENV: "production" }, // This wins
+	env: { ...defaults, PORT: "3000", API_KEY: env.API_KEY },
 });
 ```
 
-## Security best practices
+### Multiple isolated sessions
 
-### Never hardcode secrets
-
-**Bad** - Secrets in code:
+Run different tasks with different environment variables concurrently:
 
 ```typescript
-await sandbox.exec("python app.py", {
-	env: {
-		API_KEY: "sk-1234567890abcdef", // NEVER DO THIS
-	},
+// Production database session
+const prodSession = await sandbox.createSession({
+	env: { DATABASE_URL: env.PROD_DATABASE_URL },
 });
-```
-
-**Good** - Secrets from Worker environment:
 
-```typescript
-await sandbox.exec("python app.py", {
-	env: {
-		API_KEY: env.API_KEY, // From Wrangler secret
-	},
+// Staging database session
+const stagingSession = await sandbox.createSession({
+	env: { DATABASE_URL: env.STAGING_DATABASE_URL },
 });
-```
-
-Set secrets with Wrangler:
-
-```bash
-wrangler secret put API_KEY
-```
-
-## Debugging
 
-List all environment variables:
-
-```typescript
-const result = await sandbox.exec("env");
-console.log(result.stdout);
+// Run migrations on both concurrently
+await Promise.all([
+	prodSession.exec("python migrate.py"),
+	stagingSession.exec("python migrate.py"),
+]);
 ```
 
-Check specific variable:
-
-```typescript
-const result = await sandbox.exec("echo $NODE_ENV");
-console.log("NODE_ENV:", result.stdout.trim());
-```
+## Environment variable precedence
 
-## Troubleshooting
+When the same variable is set at multiple levels, the most specific level takes precedence:
 
-### Variable not set
+1. **Command-level** (highest) - Passed to `exec()` or `startProcess()` options
+2. **Sandbox or session-level** - Set with `setEnvVars()`
+3. **Container default** - Built into the Docker image with `ENV`
+4. **System default** (lowest) - Operating system defaults
 
-Verify the variable is being passed:
+Example:
 
 ```typescript
-console.log("Worker env:", env.API_KEY ? "Set" : "Missing");
-
-const result = await sandbox.exec("env | grep API_KEY", {
-	env: { API_KEY: env.API_KEY },
-});
-console.log("Sandbox:", result.stdout);
-```
-
-### Shell expansion issues
+// In Dockerfile: ENV NODE_ENV=development
 
-Use runtime-specific access instead of shell variables:
+// Sandbox-level
+await sandbox.setEnvVars({ NODE_ENV: "staging" });
 
-```typescript
-// Instead of: await sandbox.exec('echo $NODE_ENV')
-await sandbox.exec('node -e "console.log(process.env.NODE_ENV)"', {
-	env: { NODE_ENV: "production" },
+// Command-level overrides all
+await sandbox.exec("node app.js", {
+	env: { NODE_ENV: "production" }, // This wins
 });
 ```
 
diff --git a/src/content/docs/sandbox/configuration/wrangler.mdx b/src/content/docs/sandbox/configuration/wrangler.mdx
