Fix broken sandbox code examples & documentation (#26387)

Author: ghostwriternr

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

@@ -20,34 +20,42 @@ Expose services running in your sandbox via public preview URLs. See [Preview UR
 Expose a port and get a preview URL.
 
 ```ts
-const response = await sandbox.exposePort(port: number, options?: ExposePortOptions): Promise<ExposePortResponse>
+const response = await sandbox.exposePort(port: number, options: ExposePortOptions): Promise<ExposePortResponse>
 ```
 
 **Parameters**:
 
 - `port` - Port number to expose (1024-65535)
-- `options` (optional):
-  - `name` - Friendly name for the port
+- `options`:
+  - `hostname` - Your Worker's domain name (e.g., `'example.com'`). Required to construct preview URLs with wildcard subdomains like `https://8080-sandbox-abc123.example.com`. Cannot be a `.workers.dev` domain as it doesn't support wildcard DNS patterns.
+  - `name` - Friendly name for the port (optional)
 
 **Returns**: `Promise<ExposePortResponse>` with `port`, `exposedAt` (preview URL), `name`
 
 <TypeScriptExample>
 ```
+// Extract hostname from request
+const { hostname } = new URL(request.url);
+
 await sandbox.startProcess('python -m http.server 8000');
-const exposed = await sandbox.exposePort(8000);
+const exposed = await sandbox.exposePort(8000, { hostname });
 
 console.log('Available at:', exposed.exposedAt);
-// https://8000-abc123.example.com
+// https://8000-abc123.yourdomain.com
 
 // Multiple services with names
 await sandbox.startProcess('node api.js');
-const api = await sandbox.exposePort(3000, { name: 'api' });
+const api = await sandbox.exposePort(3000, { hostname, name: 'api' });
 
 await sandbox.startProcess('npm run dev');
-const frontend = await sandbox.exposePort(5173, { name: 'frontend' });
+const frontend = await sandbox.exposePort(5173, { hostname, name: 'frontend' });
 ```
 </TypeScriptExample>
 
+:::note[Local development]
+When using `wrangler dev`, you must add `EXPOSE` directives to your Dockerfile for each port. See [Expose Services guide](/sandbox/guides/expose-services/#local-development) for details.
+:::
+
 ### `unexposePort()`
 
 Remove an exposed port and close its preview URL.
@@ -111,6 +119,8 @@ const response = await sandbox.wsConnect(request: Request, port: number): Promis
 ```ts
 import { getSandbox } from "@cloudflare/sandbox";
 
+export { Sandbox } from "@cloudflare/sandbox";
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {

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

@@ -66,11 +66,16 @@ npm install express
 
 **Inbound connections** require port exposure:
 ```typescript
+const { hostname } = new URL(request.url);
 await sandbox.startProcess('python -m http.server 8000');
-const exposed = await sandbox.exposePort(8000);
+const exposed = await sandbox.exposePort(8000, { hostname });
 console.log(exposed.exposedAt); // Public URL
 ```
 
+:::note[Local development]
+When using `wrangler dev`, you must add `EXPOSE` directives to your Dockerfile for each port. See [Local development with ports](/sandbox/guides/expose-services/#local-development).
+:::
+
 **Localhost** works within sandbox:
 ```bash
 redis-server &      # Start server

src/content/docs/sandbox/concepts/preview-urls.mdx

@@ -12,20 +12,23 @@ Preview URLs work in local development without configuration. For production, yo
 Preview URLs provide public HTTPS access to services running inside sandboxes. When you expose a port, you get a unique URL that proxies requests to your service.
 
 ```typescript
+// Extract hostname from request
+const { hostname } = new URL(request.url);
+
 await sandbox.startProcess("python -m http.server 8000");
-const exposed = await sandbox.exposePort(8000);
+const exposed = await sandbox.exposePort(8000, { hostname });
 
 console.log(exposed.exposedAt);
-// Production: https://8000-abc123.example.com
+// Production: https://8000-abc123.yourdomain.com
 // Local dev: http://localhost:8787/...
 ```
 
 ## URL Format
 
 **Production**: `https://{port}-{sandbox-id}.yourdomain.com`
 
-- Port 8080: `https://8080-abc123.example.com`
-- Port 3000: `https://3000-abc123.example.com`
+- Port 8080: `https://8080-abc123.yourdomain.com`
+- Port 3000: `https://3000-abc123.yourdomain.com`
 
 **Local development**: `http://localhost:8787/...`
 
@@ -38,6 +41,8 @@ You must call `proxyToSandbox()` first in your Worker's fetch handler to route p
 ```typescript
 import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";
 
+export { Sandbox } from "@cloudflare/sandbox";
+
 export default {
 	async fetch(request, env) {
 		// Handle preview URL routing first
@@ -57,15 +62,18 @@ Requests flow: Browser → Your Worker → Durable Object (sandbox) → Your Ser
 Expose multiple services simultaneously:
 
 ```typescript
+// Extract hostname from request
+const { hostname } = new URL(request.url);
+
 await sandbox.startProcess("node api.js"); // Port 3000
 await sandbox.startProcess("node admin.js"); // Port 3001
 
-const api = await sandbox.exposePort(3000, { name: "api" });
-const admin = await sandbox.exposePort(3001, { name: "admin" });
+const api = await sandbox.exposePort(3000, { hostname, name: "api" });
+const admin = await sandbox.exposePort(3001, { hostname, name: "admin" });
 
 // Each gets its own URL:
-// https://3000-abc123.example.com
-// https://3001-abc123.example.com
+// https://3000-abc123.yourdomain.com
+// https://3001-abc123.yourdomain.com
 ```
 
 ## What Works
@@ -88,17 +96,21 @@ const admin = await sandbox.exposePort(3001, { name: "admin" });
 Preview URLs support WebSocket connections. When a WebSocket upgrade request hits an exposed port, the routing layer automatically handles the connection handshake.
 
 ```typescript
+// Extract hostname from request
+const { hostname } = new URL(request.url);
+
 // Start a WebSocket server
 await sandbox.startProcess("bun run ws-server.ts 8080");
-const { exposedAt } = await sandbox.exposePort(8080);
+const { exposedAt } = await sandbox.exposePort(8080, { hostname });
 
 // Clients connect using WebSocket protocol
-// Browser: new WebSocket('wss://8080-abc123.example.com')
+// Browser: new WebSocket('wss://8080-abc123.yourdomain.com')
 
 // Your Worker routes automatically
 export default {
 	async fetch(request, env) {
-		return proxyToSandbox(request, env.Sandbox, "sandbox-id");
+		const proxyResponse = await proxyToSandbox(request, env);
+		if (proxyResponse) return proxyResponse;
 	},
 };
 ```
@@ -113,7 +125,7 @@ Preview URLs are publicly accessible by default, but require a valid access toke
 
 **Built-in security**:
 
-- **Token-based access** - Each exposed port gets a unique token in the URL (for example, `https://8080-sandbox-abc123token.example.com`)
+- **Token-based access** - Each exposed port gets a unique token in the URL (for example, `https://8080-sandbox-abc123token.yourdomain.com`)
 - **HTTPS in production** - All traffic is encrypted with automatic TLS
 - **Unpredictable URLs** - Tokens are randomly generated and difficult to guess
 

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

@@ -81,7 +81,13 @@ export default {
 
 ### Preview URLs
 
-Preview URLs are public. Add authentication in your service:
+Preview URLs include randomly generated tokens. Anyone with the URL can access the service.
+
+To revoke access, unexpose the port:
+
+```typescript
+await sandbox.unexposePort(8080);
+```
 
 ```python
 from flask import Flask, request, abort

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

@@ -122,12 +122,6 @@ await session1.startProcess('node server.js');
 await session2.listProcesses();  // Sees the server
 ```
 
-**Ports**:
-```typescript
-await session1.exposePort(3000);
-await session2.getExposedPorts();  // Sees port 3000
-```
-
 ## When to use sessions
 
 **Use sessions when**:

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

@@ -66,6 +66,44 @@ Update `wrangler.jsonc` to reference your Dockerfile:
 
 When you run `wrangler dev` or `wrangler deploy`, Wrangler automatically builds your Docker image and pushes it to Cloudflare's container registry. You don't need to manually build or publish images.
 
+## Custom startup scripts
+
+Run services automatically when the container starts by creating a custom startup script:
+
+```dockerfile title="Dockerfile"
+FROM docker.io/cloudflare/sandbox:0.3.3
+
+COPY my-app.js /workspace/my-app.js
+COPY startup.sh /workspace/startup.sh
+RUN chmod +x /workspace/startup.sh
+CMD ["/workspace/startup.sh"]
+```
+
+```bash title="startup.sh"
+#!/bin/bash
+
+# Start your services in the background
+node /workspace/my-app.js &
+
+# Must end with this command
+exec bun /container-server/dist/index.js
+```
+
+Your startup script must end with `exec bun /container-server/dist/index.js` to start the SDK's control plane.
+
+### Multiple services
+
+```bash title="startup.sh"
+#!/bin/bash
+
+redis-server --daemonize yes
+until redis-cli ping; do sleep 1; done
+
+node /workspace/api-server.js &
+
+exec bun /container-server/dist/index.js
+```
+
 ## Related resources
 
 - [Image Management](/containers/platform-details/image-management/) - Building and pushing images to Cloudflare\'s registry

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

@@ -167,6 +167,8 @@ By default, containers automatically shut down after 10 minutes of inactivity. F
 ```ts
 import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
 
+export { Sandbox } from '@cloudflare/sandbox';
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     // Enable keepAlive for long-running processes

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

@@ -63,11 +63,11 @@ const context = await sandbox.createCodeContext({
 });
 
 // Execute code
-const result = await sandbox.runCode(context.id, `
+const result = await sandbox.runCode(`
 print("Hello from Code Interpreter!")
 result = 2 + 2
 print(f"2 + 2 = {result}")
-`);
+`, { context: context.id });
 
 console.log('Output:', result.output);
 console.log('Success:', result.success);
@@ -85,19 +85,19 @@ const context = await sandbox.createCodeContext({
 });
 
 // First execution - import and define variables
-await sandbox.runCode(context.id, `
+await sandbox.runCode(`
 import pandas as pd
 import numpy as np
 
 data = [1, 2, 3, 4, 5]
 print("Data initialized")
-`);
+`, { context: context.id });
 
 // Second execution - use previously defined variables
-const result = await sandbox.runCode(context.id, `
+const result = await sandbox.runCode(`
 mean = np.mean(data)
 print(f"Mean: {mean}")
-`);
+`, { context: context.id });
 
 console.log(result.output); // "Mean: 3.0"
 ```
@@ -113,13 +113,13 @@ The code interpreter returns multiple output formats:
 
 <TypeScriptExample>
 ```
-const result = await sandbox.runCode(context.id, `
+const result = await sandbox.runCode(`
 import matplotlib.pyplot as plt
 
 plt.plot([1, 2, 3], [1, 4, 9])
 plt.title('Simple Chart')
 plt.show()
-`);
+`, { context: context.id });
 
 // Check available formats
 console.log('Formats:', result.formats);  // ['text', 'png']
@@ -157,7 +157,6 @@ const context = await sandbox.createCodeContext({
 });
 
 const result = await sandbox.runCode(
-  context.id,
   `
 import time
 
@@ -168,6 +167,7 @@ for i in range(10):
 print("Done!")
 `,
   {
+    context: context.id,
     stream: true,
     onOutput: (data) => {
       console.log('Output:', data);
@@ -212,7 +212,7 @@ const code = content[0].text;
 
 // 2. Execute in sandbox
 const context = await sandbox.createCodeContext({ language: 'python' });
-const result = await sandbox.runCode(context.id, code);
+const result = await sandbox.runCode(code, { context: context.id });
 
 console.log('Generated code:', code);
 console.log('Output:', result.output);