Document preview URL setup

Author: ghostwriternr

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

@@ -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');

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

@@ -5,62 +5,54 @@ sidebar:
   order: 5
 ---
 
-Preview URLs provide public access to services running inside sandboxes. When you expose a port, you get a unique HTTPS URL that proxies requests to your service.
+:::note[Production requires custom domain]
+Preview URLs work in local development without configuration. For production, you need a custom domain with wildcard DNS routing. See [Production Deployment](/sandbox/guides/production-deployment/).
+:::
+
+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
 await sandbox.startProcess('python -m http.server 8000');
 const exposed = await sandbox.exposePort(8000);
 
 console.log(exposed.exposedAt);
-// https://abc123-8000.sandbox.workers.dev
+// Production: https://8000-abc123.example.com
+// Local dev: http://localhost:8787/...
 ```
 
-## URL format
+## URL Format
 
-Preview URLs follow this pattern:
-
-```
-https://{sandbox-id}-{port}.sandbox.workers.dev
-```
+**Production**: `https://{port}-{sandbox-id}.yourdomain.com`
 
-**Examples**:
-- Port 3000: `https://abc123-3000.sandbox.workers.dev`
-- Port 8080: `https://abc123-8080.sandbox.workers.dev`
+- Port 8080: `https://8080-abc123.example.com`
+- Port 3000: `https://3000-abc123.example.com`
 
-**URL stability**: URLs remain the same for a given sandbox ID and port. You can share, bookmark, or use them in webhooks.
+**Local development**: `http://localhost:8787/...`
 
-## Request routing
+URLs remain stable for a given sandbox ID and port. You can share, bookmark, or use them in webhooks.
 
-```
-User's Browser
-     ↓ HTTPS
-Your Worker
-     ↓
-Durable Object (sandbox)
-     ↓ HTTP
-Your Service (on exposed port)
-```
+## Request Routing
 
-**Important**: You must handle preview URL routing in your Worker using `proxyToSandbox()`:
+You must call `proxyToSandbox()` first in your Worker's fetch handler to route preview URL requests:
 
 ```typescript
 import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";
 
 export default {
   async fetch(request, env) {
-    // Route preview URL requests to sandboxes
+    // Handle preview URL routing first
     const proxyResponse = await proxyToSandbox(request, env);
     if (proxyResponse) return proxyResponse;
 
-    // Your custom routes here
+    // Your application routes
     // ...
   }
 };
 ```
 
-Without this, preview URLs won't work.
+Requests flow: Browser → Your Worker → Durable Object (sandbox) → Your Service.
 
-## Multiple ports
+## Multiple Ports
 
 Expose multiple services simultaneously:
 
@@ -72,19 +64,19 @@ const api = await sandbox.exposePort(3000, { name: 'api' });
 const admin = await sandbox.exposePort(3001, { name: 'admin' });
 
 // Each gets its own URL:
-// https://abc123-3000.sandbox.workers.dev
-// https://abc123-3001.sandbox.workers.dev
+// https://3000-abc123.example.com
+// https://3001-abc123.example.com
 ```
 
-## What works
+## What Works
 
 - HTTP/HTTPS requests
 - WebSocket (WSS) via HTTP upgrade
 - Server-Sent Events
 - All HTTP methods (GET, POST, PUT, DELETE, etc.)
 - Request and response headers
 
-## What doesn't work
+## What Does Not Work
 
 - Raw TCP/UDP connections
 - Custom protocols (must wrap in HTTP)
@@ -96,7 +88,7 @@ const admin = await sandbox.exposePort(3001, { name: 'admin' });
 Preview URLs are publicly accessible. Anyone with the URL can access your service.
 :::
 
-**Add authentication in your service**:
+Add authentication in your service:
 
 ```python
 from flask import Flask, request, abort
@@ -118,7 +110,7 @@ def get_data():
 
 ## Troubleshooting
 
-### URL not accessible
+### URL Not Accessible
 
 Check if service is running and listening:
 
@@ -137,19 +129,11 @@ app.run(host='0.0.0.0', port=3000)
 app.run(host='127.0.0.1', port=3000)
 ```
 
-## Best practices
-
-**Service design**:
-- Bind to `0.0.0.0` to make accessible
-- Add authentication (don't rely on URL secrecy)
-- Include health check endpoints
-- Handle CORS if accessed from browsers
+### Production Errors
 
-**Cleanup**:
-- Unexpose ports when done: `await sandbox.unexposePort(port)`
-- Stop processes: `await sandbox.killAllProcesses()`
+For custom domain issues, see [Production Deployment troubleshooting](/sandbox/guides/production-deployment/#troubleshooting).
 
-## Local development
+### Local Development
 
 :::caution[Local development only]
 When using `wrangler dev`, you must expose ports in your Dockerfile:
@@ -167,7 +151,9 @@ Without `EXPOSE`, you'll see: `connect(): Connection refused: container port not
 This is **only required for local development**. In production, all container ports are automatically accessible.
 :::
 
-## Related resources
+## Related Resources
 
-- [Ports API reference](/sandbox/api/ports/) - Complete port exposure API
-- [Expose services guide](/sandbox/guides/expose-services/) - Practical patterns
+- [Production Deployment](/sandbox/guides/production-deployment/) - Set up custom domains for production
+- [Expose Services](/sandbox/guides/expose-services/) - Practical patterns for exposing ports
+- [Ports API](/sandbox/api/ports/) - Complete API reference
+- [Security Model](/sandbox/concepts/security/) - Security best practices

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

@@ -151,7 +151,11 @@ Visit your Worker URL (shown in deploy output):
 curl https://my-sandbox.YOUR_SUBDOMAIN.workers.dev/run
 ```
 
-Your sandbox is now deployed.
+Your sandbox is now deployed and can execute code in isolated containers.
+
+:::note[Preview URLs require custom domain]
+If you plan to expose ports from sandboxes (using `exposePort()` for preview URLs), you will need to set up a custom domain with wildcard DNS routing. The `.workers.dev` domain does not support the subdomain patterns required for preview URLs. See [Production Deployment](/sandbox/guides/production-deployment/) when you are ready to expose services.
+:::
 
 ## Understanding the configuration
 
@@ -201,4 +205,5 @@ Now that you have a working sandbox, explore more capabilities:
 - [Execute commands](/sandbox/guides/execute-commands/) - Run shell commands and stream output
 - [Manage files](/sandbox/guides/manage-files/) - Work with files and directories
 - [Expose services](/sandbox/guides/expose-services/) - Get public URLs for services running in your sandbox
+- [Production Deployment](/sandbox/guides/production-deployment/) - Set up custom domains for preview URLs
 - [API reference](/sandbox/api/) - Complete API documentation

src/content/docs/sandbox/guides/expose-services.mdx

@@ -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/) for setup instructions.
+:::
+
 This guide shows you how to expose services running in your sandbox to the internet via preview URLs.
 
 ## When to expose ports
@@ -40,7 +44,8 @@ const exposed = await sandbox.exposePort(8000);
 
 // 4. Preview URL is now available (public by default)
 console.log('Server accessible at:', exposed.exposedAt);
-// Returns: https://abc123-8000.sandbox.workers.dev
+// Production: https://8000-abc123.example.com
+// Local dev: http://localhost:8787/...
 
 // 5. Handle preview URL requests in your Worker
 export default {
@@ -255,12 +260,14 @@ if (!ports.some(p => p.port === 8080)) {
 ```
 </TypeScriptExample>
 
-## Preview URL format
+## Preview URL Format
+
+**Production**: `https://{port}-{sandbox-id}.yourdomain.com`
 
-Preview URLs follow the pattern `https://{sandbox-id}-{port}.sandbox.workers.dev`:
+- Port 8080: `https://8080-abc123.example.com`
+- Port 5173: `https://5173-abc123.example.com`
 
-- Port 8080: `https://abc123-8080.sandbox.workers.dev`
-- Port 5173: `https://abc123-5173.sandbox.workers.dev`
+**Local development**: `http://localhost:8787/...`
 
 **Note**: Port 3000 is reserved for the internal Bun server and cannot be exposed.
 

src/content/docs/sandbox/guides/production-deployment.mdx

@@ -0,0 +1,92 @@
+---
+title: Deploy to Production
+pcx_content_type: how-to
+sidebar:
+  order: 10
+---
+
+import { WranglerConfig } from "~/components";
+
+:::note[Only required for preview URLs]
+Custom domain setup is ONLY needed if you use `exposePort()` to expose services from sandboxes. If your application does not expose ports, you can deploy to `.workers.dev` without this configuration.
+:::
+
+Deploy your Sandbox SDK application to production with preview URL support. Preview URLs require wildcard DNS routing because they generate unique subdomains for each exposed port: `https://8080-abc123.yourdomain.com`.
+
+The `.workers.dev` domain does not support wildcard subdomains, so production deployments that use preview URLs need a custom domain.
+
+## Prerequisites
+
+- Active Cloudflare zone with a domain
+- Worker that uses `exposePort()`
+- [Wrangler CLI](/workers/wrangler/install-and-update/) installed
+
+## Setup
+
+### Create Wildcard DNS Record
+
+In the Cloudflare dashboard, go to your domain and create an A record:
+
+- **Type**: A
+- **Name**: * (wildcard)
+- **IPv4 address**: 192.0.2.0
+- **Proxy status**: Proxied (orange cloud)
+
+This routes all subdomains through Cloudflare's proxy. The IP address `192.0.2.0` is a documentation address (RFC 5737) that Cloudflare recognizes when proxied.
+
+### Configure Worker Routes
+
+Add a wildcard route to your Wrangler configuration:
+
+<WranglerConfig>
+```toml
+name = "my-sandbox-app"
+main = "src/index.ts"
+compatibility_date = "$today"
+
+[[routes]]
+pattern = "*.yourdomain.com/*"
+zone_name = "yourdomain.com"
+```
+</WranglerConfig>
+
+Replace `yourdomain.com` with your actual domain. This routes all subdomain requests to your Worker and enables Cloudflare to provision SSL certificates automatically.
+
+### Deploy
+
+Deploy your Worker:
+
+```sh
+npx wrangler deploy
+```
+
+## Verify
+
+Test that preview URLs work:
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, 'test-sandbox');
+await sandbox.startProcess('python -m http.server 8080');
+const exposed = await sandbox.exposePort(8080);
+
+console.log(exposed.exposedAt);
+// https://8080-test-sandbox.yourdomain.com
+```
+
+Visit the URL in your browser to confirm your service is accessible.
+
+## Troubleshooting
+
+- **CustomDomainRequiredError**: Verify your Worker is not deployed to `.workers.dev` and that the wildcard DNS record and route are configured correctly.
+- **SSL/TLS errors**: Wait a few minutes for certificate provisioning. Verify the DNS record is proxied and SSL/TLS mode is set to "Full" or "Full (strict)" in your dashboard.
+- **Preview URL not resolving**: Confirm the wildcard DNS record exists and is proxied. Wait 30-60 seconds for DNS propagation.
+- **Port not accessible**: Ensure your service binds to `0.0.0.0` (not `localhost`) and that `proxyToSandbox()` is called first in your Worker's fetch handler.
+
+For detailed troubleshooting, see the [Workers routing documentation](/workers/configuration/routing/).
+
+## Related Resources
+
+- [Preview URLs](/sandbox/concepts/preview-urls/) - How preview URLs work
+- [Expose Services](/sandbox/guides/expose-services/) - Patterns for exposing ports
+- [Workers Routing](/workers/configuration/routing/) - Advanced routing configuration
+- [Cloudflare DNS](/dns/) - DNS management