Support undefined/null as unset in setEnvVars (#27609)

* Support undefined/null as unset in environment variable APIs

Document new behavior where undefined/null values in setEnvVars, exec options,
and session creation now unset variables instead of throwing errors.

- Add new 'Unsetting environment variables' section with examples
- Update type signatures to Record<string, string | undefined>
- Add examples showing undefined behavior in all env contexts
- Document use cases for conditional environment setup

Related to cloudflare/sandbox-sdk PR #342

* Fixed 3 minor issues across sandbox docs

Co-authored-by: elithrar <elithrar@users.noreply.github.com>

* Fix merge-damaged code indentation

Co-authored-by: elithrar <elithrar@users.noreply.github.com>

---------

Co-authored-by: OpenCode <opencode@anthropic.com>
Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
Co-authored-by: elithrar <elithrar@users.noreply.github.com>
Co-authored-by: Matt Silverlock <matt@eatsleeprepeat.net>

Author: 4 people

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

@@ -20,11 +20,14 @@ const result = await sandbox.exec(command: string, options?: ExecOptions): Promi
 ```
 
 **Parameters**:
+
 - `command` - The command to execute (can include arguments)
 - `options` (optional):
   - `stream` - Enable streaming callbacks (default: `false`)
   - `onOutput` - Callback for real-time output: `(stream: 'stdout' | 'stderr', data: string) => void`
   - `timeout` - Maximum execution time in milliseconds
+  - `env` - Environment variables for this command: `Record<string, string | undefined>`
+  - `cwd` - Working directory for this command
   - `stdin` - Data to pass to the command's standard input (enables arbitrary input without shell injection risks)
 
 **Returns**: `Promise<ExecuteResponse>` with `success`, `stdout`, `stderr`, `exitCode`
@@ -45,6 +48,15 @@ await sandbox.exec('npm install', {
   onOutput: (stream, data) => console.log(`[${stream}] ${data}`)
 });
 
+// With environment variables (undefined values are skipped)
+await sandbox.exec('node app.js', {
+  env: {
+    NODE_ENV: 'production',
+    PORT: '3000',
+    DEBUG_MODE: undefined // Skipped, uses container default or unset
+  }
+});
+
 // Pass input via stdin (no shell injection risks)
 const result = await sandbox.exec('cat', {
   stdin: 'Hello, world!'
@@ -68,6 +80,7 @@ const stream = await sandbox.execStream(command: string, options?: ExecOptions):
 ```
 
 **Parameters**:
+
 - `command` - The command to execute
 - `options` - Same as `exec()` (including `stdin` support)
 
@@ -115,13 +128,19 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
 ```
 
 **Parameters**:
+
 - `command` - The command to start as a background process
 - `options` (optional):
   - `cwd` - Working directory
-  - `env` - Environment variables
+  - `env` - Environment variables: `Record<string, string | undefined>`
   - `stdin` - Data to pass to the command's standard input
+  - `timeout` - Maximum execution time in milliseconds
+  - `processId` - Custom process ID
+  - `encoding` - Output encoding (default: `'utf8'`)
+  - `autoCleanup` - Whether to clean up process on sandbox sleep
 
 **Returns**: `Promise<Process>` object with:
+
 - `id` - Unique process identifier
 - `pid` - System process ID
 - `command` - The command being executed
@@ -178,6 +197,7 @@ await sandbox.killProcess(processId: string, signal?: string): Promise<void>
 ```
 
 **Parameters**:
+
 - `processId` - The process ID (from `startProcess()` or `listProcesses()`)
 - `signal` - Signal to send (default: `"SIGTERM"`)
 
@@ -218,6 +238,7 @@ const stream = await sandbox.streamProcessLogs(processId: string): Promise<Reada
 ```
 
 **Parameters**:
+
 - `processId` - The process ID
 
 **Returns**: `Promise<ReadableStream>` emitting `LogEvent` objects
@@ -246,6 +267,7 @@ const logs = await sandbox.getProcessLogs(processId: string): Promise<string>
 ```
 
 **Parameters**:
+
 - `processId` - The process ID
 
 **Returns**: `Promise<string>` with all accumulated output
@@ -341,6 +363,7 @@ await process.waitForPort(port: number, options?: WaitForPortOptions): Promise<v
 ```
 
 **Parameters**:
+
 - `port` - The port number to check
 - `options` (optional):
   - `mode` - Check mode: `'http'` (default) or `'tcp'`
@@ -394,10 +417,12 @@ const result = await process.waitForLog(pattern: string | RegExp, timeout?: numb
 ```
 
 **Parameters**:
+
 - `pattern` - String or RegExp to match in stdout/stderr
 - `timeout` - Maximum wait time in milliseconds (optional)
 
 **Returns**: `Promise<WaitForLogResult>` with:
+
 - `line` - The matching line of output
 - `matches` - Array of capture groups (for RegExp patterns)
 
@@ -431,9 +456,11 @@ const result = await process.waitForExit(timeout?: number): Promise<WaitForExitR
 ```
 
 **Parameters**:
+
 - `timeout` - Maximum wait time in milliseconds (optional)
 
 **Returns**: `Promise<WaitForExitResult>` with:
+
 - `exitCode` - The process exit code
 
 <TypeScriptExample>

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

@@ -29,7 +29,7 @@ const response = await sandbox.exposePort(port: number, options: ExposePortOptio
 - `options`:
   - `hostname` - Your Worker's domain name (e.g., `'example.com'`). Required to construct preview URLs with wildcard subdomains like `https://8080-sandbox-abc123token.example.com`. Cannot be a `.workers.dev` domain as it doesn't support wildcard DNS patterns.
   - `name` - Friendly name for the port (optional)
-  - `token` - Custom token for the preview URL (optional). Must be 1-16 characters containing only lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_). If not provided, a random 16-character token is generated automatically.
+  - `token` - Custom token for the preview URL (optional). Must be 1-16 characters containing only lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (\_). If not provided, a random 16-character token is generated automatically.
 
 **Returns**: `Promise<ExposePortResponse>` with `port`, `url` (preview URL), `name`
 
@@ -55,8 +55,8 @@ console.log('Stable URL:', stable.url);
 
 // With custom token for stable URLs across deployments
 await sandbox.startProcess('node api.js');
-const api = await sandbox.exposePort(3000, { 
-  hostname, 
+const api = await sandbox.exposePort(3000, {
+  hostname,
   name: 'api',
   token: 'prod-api-v1'  // URL stays same across restarts
 });
@@ -66,8 +66,8 @@ console.log('Stable API URL:', api.url);
 
 // Multiple services with custom tokens
 await sandbox.startProcess('npm run dev');
-const frontend = await sandbox.exposePort(5173, { 
-  hostname, 
+const frontend = await sandbox.exposePort(5173, {
+  hostname,
   name: 'frontend',
   token: 'dev-ui'
 });

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

@@ -26,7 +26,7 @@ const session = await sandbox.createSession(options?: SessionOptions): Promise<E
 **Parameters**:
 - `options` (optional):
   - `id` - Custom session ID (auto-generated if not provided)
-  - `env` - Environment variables for this session
+  - `env` - Environment variables for this session: `Record<string, string | undefined>`
   - `cwd` - Working directory (default: `"/workspace"`)
 
 **Returns**: `Promise<ExecutionSession>` with all sandbox methods bound to this session
@@ -42,7 +42,11 @@ const prodSession = await sandbox.createSession({
 
 const testSession = await sandbox.createSession({
   id: 'test',
-  env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
+  env: { 
+    NODE_ENV: 'test', 
+    API_URL: 'http://localhost:3000',
+    DEBUG_MODE: undefined  // Skipped, not set in this session
+  },
   cwd: '/workspace/test'
 });
 
@@ -123,11 +127,13 @@ Deleting a session immediately terminates all running commands. The default sess
 Set environment variables in the sandbox.
 
 ```ts
-await sandbox.setEnvVars(envVars: Record<string, string>): Promise<void>
+await sandbox.setEnvVars(envVars: Record<string, string | undefined>): Promise<void>
 ```
 
 **Parameters**:
-- `envVars` - Key-value pairs of environment variables to set
+- `envVars` - Key-value pairs of environment variables to set or unset
+  - `string` values: Set the environment variable
+  - `undefined` or `null` values: Unset the environment variable
 
 :::caution
 Call `setEnvVars()` **before** any other sandbox operations to ensure environment variables are available from the start.
@@ -141,7 +147,8 @@ const sandbox = getSandbox(env.Sandbox, 'user-123');
 await sandbox.setEnvVars({
   API_KEY: env.OPENAI_API_KEY,
   DATABASE_URL: env.DATABASE_URL,
-  NODE_ENV: 'production'
+  NODE_ENV: 'production',
+  OLD_TOKEN: undefined  // Unsets OLD_TOKEN if previously set
 });
 
 // Now commands can access these variables

src/content/docs/sandbox/configuration/environment-variables.mdx

@@ -36,6 +36,16 @@ await sandbox.setEnvVars({
 
 **Use when:** You need the same environment variables for multiple commands.
 
+**Unsetting variables**: Pass `undefined` or `null` to unset environment variables:
+
+```typescript
+await sandbox.setEnvVars({
+	API_KEY: 'new-key',     // Sets API_KEY
+	OLD_SECRET: undefined,  // Unsets OLD_SECRET
+	DEBUG_MODE: null        // Unsets DEBUG_MODE
+});
+```
+
 ### 2. Per-command with exec() options
 
 Pass environment variables for a specific command:
@@ -81,6 +91,56 @@ await session.exec("python seed.py");
 
 **Use when:** You need isolated execution contexts with different environment variables running concurrently.
 
+## Unsetting environment variables
+
+The Sandbox SDK supports unsetting environment variables by passing `undefined` or `null` values. This enables idiomatic JavaScript patterns for managing configuration:
+
+```typescript
+await sandbox.setEnvVars({
+	// Set new values
+	API_KEY: 'new-key',
+	DATABASE_URL: env.DATABASE_URL,
+	
+	// Unset variables (removes them from the environment)
+	OLD_API_KEY: undefined,
+	TEMP_TOKEN: null
+});
+```
+
+**Before this change**: Passing `undefined` values would throw a runtime error.
+
+**After this change**: `undefined` and `null` values run `unset VARIABLE_NAME` in the shell.
+
+### Use cases for unsetting
+
+**Remove sensitive data after use:**
+
+```typescript
+// Use a temporary token
+await sandbox.setEnvVars({ TEMP_TOKEN: 'abc123' });
+await sandbox.exec('curl -H "Authorization: $TEMP_TOKEN" api.example.com');
+
+// Clean up the token
+await sandbox.setEnvVars({ TEMP_TOKEN: undefined });
+```
+
+**Conditional environment setup:**
+
+```typescript
+await sandbox.setEnvVars({
+	API_KEY: env.API_KEY,
+	DEBUG_MODE: env.NODE_ENV === 'development' ? 'true' : undefined,
+	PROFILING: env.ENABLE_PROFILING ? 'true' : undefined
+});
+```
+
+**Reset to system defaults:**
+
+```typescript
+// Unset to fall back to container's default NODE_ENV
+await sandbox.setEnvVars({ NODE_ENV: undefined });
+```
+
 ## Common patterns
 
 ### Pass Worker secrets to sandbox

src/content/docs/sandbox/tutorials/claude-code.mdx

@@ -18,6 +18,7 @@ Build a Worker that takes a repository URL and a task description and uses Sandb
 <Render file="prereqs" product="workers" />
 
 You'll also need:
+
 - An [Anthropic API key](https://console.anthropic.com/) for Claude Code
 - [Docker](https://www.docker.com/) running locally
 
@@ -28,7 +29,9 @@ Create a new Sandbox SDK project:
 <PackageManagers
 	type="create"
 	pkg="cloudflare@latest"
-	args={"claude-code-sandbox --template=cloudflare/sandbox-sdk/examples/claude-code"}
+	args={
+		"claude-code-sandbox --template=cloudflare/sandbox-sdk/examples/claude-code"
+	}
 />
 
 ```sh
@@ -75,8 +78,8 @@ Response:
 
 ```json
 {
-  "logs": "Done! I've removed the brain emoji from the README title. The heading now reads \"# Cloudflare Agents\" instead of \"# 🧠 Cloudflare Agents\".",
-  "diff": "diff --git a/README.md b/README.md\nindex 9296ac9..027c218 100644\n--- a/README.md\n+++ b/README.md\n@@ -1,4 +1,4 @@\n-# 🧠 Cloudflare Agents\n+# Cloudflare Agents\n \n ![npm install agents](assets/npm-install-agents.svg)\n "
+	"logs": "Done! I've removed the brain emoji from the README title. The heading now reads \"# Cloudflare Agents\" instead of \"# 🧠 Cloudflare Agents\".",
+	"diff": "diff --git a/README.md b/README.md\nindex 9296ac9..027c218 100644\n--- a/README.md\n+++ b/README.md\n@@ -1,4 +1,4 @@\n-# 🧠 Cloudflare Agents\n+# Cloudflare Agents\n \n ![npm install agents](assets/npm-install-agents.svg)\n "
 }
 ```
 
@@ -103,6 +106,7 @@ After first deployment, wait 2-3 minutes for container provisioning. Check statu
 ## What you built
 
 You created an API that:
+
 - Accepts a repository URL and natural language task descriptions
 - Creates a Sandbox and clones the repository into it
 - Kicks off Claude Code to implement the given task