cloudflare · whoiskatrin · Oct 21, 2025 · Oct 20, 2025 · Oct 20, 2025 · Oct 20, 2025
@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-import { WranglerConfig, PackageManagers } from "~/components";
+import { Render, PackageManagers, WranglerConfig } from "~/components";
 
 In this guide, you will deploy a Worker that can make requests to one or more Containers in response to end-user requests.
 In this example, each container runs a small webserver written in Go.
@@ -17,10 +17,9 @@ This example Worker should give you a sense for simple Container use, and provid
 ### Ensure Docker is running locally
 
 In this guide, we will build and push a container image alongside your Worker code. By default, this process uses
-[Docker](https://www.docker.com/) to do so. You must have Docker running locally when you run `wrangler deploy`. For most people, the best way to install Docker is to follow the [docs for installing Docker Desktop](https://docs.docker.com/desktop/). Other tools like [Colima](https://github.com/abiosoft/colima) may also work.
+[Docker](https://www.docker.com/) to do so.
 
-You can check that Docker is running properly by running the `docker info` command in your terminal. If Docker is running, the command will succeed. If Docker is not running,
-the `docker info` command will hang or return an error including the message "Cannot connect to the Docker daemon".
+<Render product="containers" file="docker-setup" />
 
 {/* FUTURE CHANGE: Add some image you can use if you don't have Docker running. */}
 {/* FUTURE CHANGE: Link to docs on alternative build/push options */}

@@ -17,7 +17,7 @@ import { getSandbox } from '@cloudflare/sandbox';
 const sandbox = getSandbox(env.Sandbox, 'user-123');
 ```
 
-The sandbox ID should be unique per user or session. The same ID will always return the same sandbox instance with persistent state.
+The same sandbox ID will always return the same sandbox instance. You can architect your application to use a single sandbox ID for multiple users, or use unique IDs per user or session. Using unique sandbox IDs per user is recommended if you are providing code generation or execution capabilities directly to your users.
 
 ## API organization
 

@@ -7,6 +7,10 @@ sidebar:
 
 import { TypeScriptExample } from "~/components";
 
+:::note[Production requires custom domain]
+Preview URLs require a custom domain with wildcard DNS routing in production. See [Production Deployment](/sandbox/guides/production-deployment/).
+:::
+
 Expose services running in your sandbox via public preview URLs. See [Preview URLs concept](/sandbox/concepts/preview-urls/) for details.
 
 ## Methods
@@ -32,7 +36,7 @@ await sandbox.startProcess('python -m http.server 8000');
 const exposed = await sandbox.exposePort(8000);
 
 console.log('Available at:', exposed.exposedAt);
-// https://abc123-8000.sandbox.workers.dev
+// https://8000-abc123.example.com
 
 // Multiple services with names
 await sandbox.startProcess('node api.js');

@@ -5,39 +5,37 @@ sidebar:
   order: 1
 ---
 
-The Sandbox SDK provides isolated code execution environments on Cloudflare's edge network. It combines three Cloudflare technologies:
+Sandbox SDK lets you execute untrusted code safely from your Workers. It combines three Cloudflare technologies to provide secure, stateful, and isolated execution:
 
-- **Workers** - JavaScript runtime at the edge
-- **Durable Objects** - Stateful compute with persistent storage
-- **Containers** - Isolated execution environments with full Linux capabilities
+- **Workers** - Your application logic that calls the Sandbox SDK
+- **Durable Objects** - Persistent sandbox instances with unique identities
+- **Containers** - Isolated Linux environments where code actually runs
 
-## Three-layer architecture
+## Architecture overview
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                     Your Application                    │
-│                    (Cloudflare Worker)                  │
-└───────────────────────────┬─────────────────────────────┘
-                            ├─ getSandbox()
-                            ├─ exec()
-                            ├─ writeFile()
-                            │
-           ┌────────────────▼──────────────────┐
-           │ Container-enabled Durable Object  │
-           │ (SDK methods via RPC from Worker) │
-           └───────────────────────────────────┘
-                            │ HTTP/JSON
-                            │
-                    ┌───────▼───────┐
-                    │ Durable Object │ Layer 2: State Management
-                    │  (Persistent)  │
-                    └───────┬───────┘
-                            │ Container Protocol
-                            │
-                    ┌───────▼───────┐
-                    │   Container   │ Layer 3: Isolated Execution
-                    │  (Linux + Bun) │
-                    └───────────────┘
+```mermaid
+flowchart TB
+    accTitle: Sandbox SDK Architecture
+    accDescr: Three-layer architecture showing how Cloudflare Sandbox SDK combines Workers, Durable Objects, and Containers for secure code execution
+
+    subgraph UserSpace["<b>Your Worker</b>"]
+        Worker["Application code using the methods exposed by the Sandbox SDK"]
+    end
+
+    subgraph SDKSpace["<b>Sandbox SDK Implementation</b>"]
+        DO["Sandbox Durable Object routes requests & maintains state"]
+        Container["Isolated Ubuntu container executes untrusted code safely"]
+
+        DO -->|HTTP API| Container
+    end
+
+    Worker -->|RPC call via the Durable Object stub returned by `getSandbox`| DO
+
+    style UserSpace fill:#fff8f0,stroke:#f6821f,stroke-width:2px
+    style SDKSpace fill:#f5f5f5,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
+    style Worker fill:#ffe8d1,stroke:#f6821f,stroke-width:2px
+    style DO fill:#dce9f7,stroke:#1d8cf8,stroke-width:2px
+    style Container fill:#d4f4e2,stroke:#17b26a,stroke-width:2px
 ```
 
 ### Layer 1: Client SDK
@@ -70,7 +68,7 @@ export class Sandbox extends DurableObject<Env> {
 **Why Durable Objects**:
 
 - **Persistent identity** - Same sandbox ID always routes to same instance
-- **State management** - Filesystem and processes persist between requests
+- **Container management** - Durable Object owns and manages the container lifecycle
 - **Geographic distribution** - Sandboxes run close to users
 - **Automatic scaling** - Cloudflare manages provisioning
 
@@ -82,9 +80,8 @@ Executes code in isolation with full Linux capabilities.
 
 **Why containers**:
 
-- **True isolation** - Process-level isolation with namespaces
-- **Full environment** - Real Linux with Python, Node.js, Git, etc.
-- **Resource limits** - CPU, memory, disk constraints
+- **VM-based isolation** - Each sandbox runs in its own VM
+- **Full environment** - Ubuntu Linux with Python, Node.js, Git, etc.
 
 ## Request flow
 
@@ -99,32 +96,6 @@ await sandbox.exec("python script.py");
 3. **Container Runtime** validates inputs, executes command, captures output
 4. **Response flows back** through all layers with proper error transformation
 
-## State persistence
-
-Sandboxes maintain state across requests:
-
-**Filesystem**:
-
-```typescript
-// Request 1
-await sandbox.writeFile("/workspace/data.txt", "hello");
-
-// Request 2 (minutes later)
-const file = await sandbox.readFile("/workspace/data.txt");
-// Returns 'hello' - file persisted
-```
-
-**Processes**:
-
-```typescript
-// Request 1
-await sandbox.startProcess("node server.js");
-
-// Request 2 (minutes later)
-const processes = await sandbox.listProcesses();
-// Server still running
-```
-
 ## Related resources
 
 - [Sandbox lifecycle](/sandbox/concepts/sandboxes/) - How sandboxes are created and managed

@@ -5,36 +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 pre-packaged with a full development environment:
-
-**Languages and runtimes**:
-- Python 3.11 (with pip)
-- Node.js 20 LTS (with npm)
-- Bun (JavaScript/TypeScript runtime)
-
-**Python packages**:
-- NumPy - Numerical computing
-- pandas - Data analysis
-- Matplotlib - Plotting and visualization
-- IPython - Interactive Python
-
-**Development tools**:
-- Git - Version control
-- Build tools (gcc, make, pkg-config)
-- Text editors (vim, nano)
-- Process monitoring (htop, procps)
-
-**Utilities**:
-- curl, wget - HTTP clients
-- jq - JSON processor
-- Network tools (ping, dig, netstat)
-- Compression (zip, unzip)
-
-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
@@ -43,8 +18,8 @@ pip install scikit-learn tensorflow
 # Node.js packages
 npm install express
 
-# System packages
-apt-get install redis-server
+# System packages (requires apt-get update first)
+apt-get update && apt-get install -y redis-server
 ```
 
 ## Filesystem

@@ -7,8 +7,6 @@ sidebar:
 
 These pages explain how the Sandbox SDK works, why it's designed the way it is, and the concepts you need to understand to use it effectively.
 
-## Available concepts
-
 - [Architecture](/sandbox/concepts/architecture/) - How the SDK is structured and why
 - [Sandbox lifecycle](/sandbox/concepts/sandboxes/) - Understanding sandbox states and behavior
 - [Container runtime](/sandbox/concepts/containers/) - How code executes in isolated containers