Add documentation for lean and Python image variants

Sync documentation for sandbox-sdk PR #259 which introduces optimized
Docker image variants.

Changes:
- Add image variant documentation to Dockerfile reference
- Update getting started guide with image selection guidance
- Add Python runtime requirements to code execution guide
- Document PYTHON_NOT_AVAILABLE error in interpreter API
- Add changelog entry for breaking change

Breaking change: Default image no longer includes Python. Users must
explicitly use the -python image variant for Python code execution.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: github-actions[bot]

src/content/changelog/agents/2025-11-27-sandbox-image-variants.mdx

@@ -0,0 +1,87 @@
+---
+title: Sandbox SDK adds lean and Python image variants
+description: Docker image size reduced by up to 62% with new lean and Python image variants. Breaking change for Python users.
+products:
+  - agents
+  - workers
+date: 2025-11-27
+---
+
+The Sandbox SDK now offers two optimized Docker image variants to improve performance and reduce resource usage.
+
+## Breaking change
+
+**The default image no longer includes Python.** If you use Python code execution, you must update your Dockerfile.
+
+## New image variants
+
+### Default image (lean)
+
+The new default image is optimized for JavaScript, TypeScript, and shell workloads:
+
+- **Size**: ~600-800 MB (62% smaller than previous default)
+- **Includes**: Node.js, Bun, Git, system utilities
+- **Use for**: JavaScript/TypeScript execution, shell scripts, Git workflows
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.6
+```
+
+### Python image
+
+The Python image includes everything from the default image plus Python runtime and data science packages:
+
+- **Size**: ~1.3 GB (26% smaller than previous default)
+- **Includes**: Python 3.11, matplotlib, numpy, pandas, ipython
+- **Use for**: Python code execution, data analysis, AI/ML workflows
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+## Migration guide
+
+If your application uses any of these features, update your Dockerfile to use the Python image:
+
+- `CodeInterpreter.runCode()` with Python
+- Python scripts via `exec()` or `startProcess()`
+- Python-based tools or workflows
+
+### Before (version 0.5.5 and earlier)
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.5
+```
+
+### After (version 0.5.6+)
+
+```dockerfile
+# For Python support
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+
+# Or for JavaScript/shell only
+FROM docker.io/cloudflare/sandbox:0.5.6
+```
+
+## Error handling
+
+If you attempt to execute Python code without the Python image, you will receive a clear error:
+
+- **Error code**: `PYTHON_NOT_AVAILABLE`
+- **HTTP status**: 501 Not Implemented
+- **Message**: Python is not available in this container
+
+The error message includes instructions to update your Dockerfile to the Python image variant.
+
+## Benefits
+
+- **Faster cold starts**: Smaller images load and start faster
+- **Lower resource usage**: Reduced memory footprint for non-Python workloads
+- **Better optimization**: Each variant is optimized for its specific use case
+- **Cost savings**: Smaller images reduce storage and bandwidth costs
+
+## Learn more
+
+- [Dockerfile reference](/sandbox/configuration/dockerfile/) - Complete guide to image variants
+- [Code Interpreter API](/sandbox/api/interpreter/) - Python code execution documentation
+- [Getting started](/sandbox/get-started/) - Updated quickstart guide

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

@@ -9,6 +9,18 @@ import { TypeScriptExample } from "~/components";
 
 Execute Python, JavaScript, and TypeScript code with support for data visualizations, tables, and rich output formats. Contexts maintain state (variables, imports, functions) across executions.
 
+:::caution[Python runtime requirements]
+To execute Python code, your container must use the Python image variant:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+The default image does not include Python. Attempting to create a Python context or run Python code without the Python image will return a `PYTHON_NOT_AVAILABLE` error with HTTP 501 status.
+
+See [Dockerfile reference](/sandbox/configuration/dockerfile/) for details.
+:::
+
 ## Methods
 
 ### `createCodeContext()`
@@ -114,13 +126,24 @@ console.log(result.results[0].text); // "15"
 
 <TypeScriptExample>
 ```
+// Runtime errors in code execution
 const result = await sandbox.runCode('x = 1 / 0', { language: 'python' });
 
 if (result.error) {
   console.error(result.error.name);      // "ZeroDivisionError"
   console.error(result.error.value);     // "division by zero"
   console.error(result.error.traceback); // Stack trace array
 }
+
+// Python not available error
+try {
+  const ctx = await sandbox.createCodeContext({ language: 'python' });
+} catch (error) {
+  // Error: Python is not available in this container
+  // Solution: Update Dockerfile to use Python image variant
+  // FROM docker.io/cloudflare/sandbox:0.5.6-python
+  console.error(error.message);
+}
 ```
 </TypeScriptExample>
 

src/content/docs/sandbox/configuration/dockerfile.mdx

@@ -11,9 +11,9 @@ Customize the sandbox container image with your own packages, tools, and configu
 
 The Sandbox SDK provides two image variants optimized for different use cases:
 
-### Default (lean) image
+### Default image (lean)
 
-Optimized for shell commands and JavaScript/TypeScript execution (~600-800MB):
+Optimized for shell scripts, JavaScript, TypeScript, and Node.js workloads (~600-800 MB):
 
 ```dockerfile
 FROM docker.io/cloudflare/sandbox:0.5.6
@@ -28,7 +28,7 @@ FROM docker.io/cloudflare/sandbox:0.5.6
 
 ### Python image
 
-Full image with Python and data science packages (~1.3GB):
+Full-featured image with Python and data science packages (~1.3 GB):
 
 ```dockerfile
 FROM docker.io/cloudflare/sandbox:0.5.6-python
@@ -39,26 +39,52 @@ FROM docker.io/cloudflare/sandbox:0.5.6-python
 - Python 3.11.14 with pip and venv
 - Pre-installed Python packages: matplotlib, numpy, pandas, ipython
 
-:::note[Choosing the right variant]
-Use the default (lean) image for shell operations, JavaScript/TypeScript execution, and Git workflows. Only use the `-python` variant if you need Python code execution with [`CodeInterpreter.runCode()`](/sandbox/api/interpreter/).
+:::caution[Breaking change: Python now requires explicit image selection]
+**Starting in version 0.5.6**, the default image no longer includes Python. If your code uses:
 
-Using the lean image reduces image size by ~500MB and improves cold start times.
+- `CodeInterpreter.runCode()` with Python
+- Python scripts via `exec()` or `startProcess()`
+- Any Python-based workflows
+
+You **must** update your Dockerfile to use the `-python` variant:
+
+```dockerfile
+# Before (0.5.5 and earlier)
+FROM docker.io/cloudflare/sandbox:0.5.5
+
+# After (0.5.6+)
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+Without this change, Python execution will fail with `PYTHON_NOT_AVAILABLE` error.
 :::
 
-:::caution[Version synchronization required]
-Always match the Docker image version to your npm package version. If you're using `@cloudflare/sandbox@0.5.6`, use `docker.io/cloudflare/sandbox:0.5.6` (or `0.5.6-python`) as your base image.
+:::note[Version synchronization required]
+Always match the Docker image version to your npm package version. If you are using `@cloudflare/sandbox@0.5.6`, use `docker.io/cloudflare/sandbox:0.5.6` (or `0.5.6-python`) as your base image.
 
-**Why this matters**: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions don't match, you'll see warnings in your logs.
+**Why this matters**: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions do not match, you will see warnings in your logs.
 
 See [Version compatibility](/sandbox/concepts/sandboxes/#version-compatibility) for troubleshooting version mismatch warnings.
 :::
 
+### Choosing an image variant
+
+Use the **default image** if you:
+- Execute shell scripts, JavaScript, or TypeScript only
+- Want faster cold starts and lower resource usage
+- Do not need Python or Python packages
+
+Use the **Python image** if you:
+- Execute Python code via `CodeInterpreter`
+- Use Python scripts or tools
+- Need data science packages (pandas, numpy, matplotlib)
+
 ## Creating a custom image
 
 Create a `Dockerfile` in your project root:
 
 ```dockerfile title="Dockerfile"
-# Use Python variant if you need Python packages
+# Choose the appropriate base image
 FROM docker.io/cloudflare/sandbox:0.5.6-python
 
 # Install additional Python packages
@@ -97,7 +123,6 @@ When you run `wrangler dev` or `wrangler deploy`, Wrangler automatically builds
 Run services automatically when the container starts by creating a custom startup script:
 
 ```dockerfile title="Dockerfile"
-# Choose appropriate variant (default or -python)
 FROM docker.io/cloudflare/sandbox:0.5.6
 
 COPY my-app.js /workspace/my-app.js
@@ -131,22 +156,9 @@ node /workspace/api-server.js &
 exec bun /container-server/dist/index.js
 ```
 
-## Migration guide
-
-If you are upgrading from a version prior to 0.5.6 and use Python code execution, update your Dockerfile to use the `-python` variant:
-
-```diff title="Dockerfile"
-- FROM docker.io/cloudflare/sandbox:0.5.5
-+ FROM docker.io/cloudflare/sandbox:0.5.6-python
-```
-
-**Why this change was made**: Separating Python into its own image variant reduces the default image size by ~500MB, improving cold start times for workloads that do not require Python.
-
-If you attempt to execute Python code without the `-python` variant, you will receive a `PYTHON_NOT_AVAILABLE` error with instructions to update your Dockerfile.
-
 ## Related resources
 
-- [Image Management](/containers/platform-details/image-management/) - Building and pushing images to Cloudflare's registry
+- [Image Management](/containers/platform-details/image-management/) - Building and pushing images to Cloudflare\'s registry
 - [Wrangler configuration](/sandbox/configuration/wrangler/) - Using custom images in wrangler.jsonc
 - [Docker documentation](https://docs.docker.com/reference/dockerfile/) - Complete Dockerfile syntax
 - [Container concepts](/sandbox/concepts/containers/) - Understanding the runtime environment

src/content/docs/sandbox/get-started.mdx

@@ -37,12 +37,26 @@ This creates a `my-sandbox` directory with everything you need:
 
 - `src/index.ts` - Worker with sandbox integration
 - `wrangler.jsonc` - Configuration for Workers and Containers
-- `Dockerfile` - Container environment definition
+- `Dockerfile` - Container environment definition (includes Python by default)
 
 ```sh
 cd my-sandbox
 ```
 
+:::note[Image variants]
+The template uses the Python image variant (`cloudflare/sandbox:<version>-python`) by default. If you only need JavaScript/shell execution and want a smaller image (~600-800 MB vs ~1.3 GB), you can change the Dockerfile to use the default image:
+
+```dockerfile
+# Lean image (no Python)
+FROM docker.io/cloudflare/sandbox:0.5.6
+
+# Full image (with Python)
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+See [Dockerfile reference](/sandbox/configuration/dockerfile/) for details on choosing the right image variant.
+:::
+
 ## 2. Explore the template
 
 The template provides a minimal Worker that demonstrates core sandbox capabilities:

src/content/docs/sandbox/guides/code-execution.mdx

@@ -36,6 +36,20 @@ Use `exec()` for **advanced or custom workflows**:
 - **Shell commands** - Git operations, system utilities, complex pipelines
 - **Long-running processes** - Background services, servers
 
+## Python runtime requirements
+
+:::caution[Python image required]
+To execute Python code, your Dockerfile **must** use the Python image variant:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+The default image (`cloudflare/sandbox:0.5.6`) does not include Python. If you attempt to run Python code without the Python image, you will receive a `PYTHON_NOT_AVAILABLE` error.
+
+See [Dockerfile reference](/sandbox/configuration/dockerfile/) for details on image variants.
+:::
+
 ## Create an execution context
 
 Code contexts maintain state between executions:
@@ -46,15 +60,15 @@ import { getSandbox } from '@cloudflare/sandbox';
 
 const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
 
-// Create a Python context
+// Create a Python context (requires Python image)
 const pythonContext = await sandbox.createCodeContext({
   language: 'python'
 });
 
 console.log('Context ID:', pythonContext.id);
 console.log('Language:', pythonContext.language);
 
-// Create a JavaScript context
+// Create a JavaScript context (works on both image variants)
 const jsContext = await sandbox.createCodeContext({
   language: 'javascript'
 });