Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Deploy to Production

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 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:

JSONC
{
 "$schema": "./node_modules/wrangler/config-schema.json",
 "name": "my-sandbox-app",
 "main": "src/index.ts",
 // Set this to today's date
 "compatibility_date": "2026-04-12",
 "routes": [
 {
 "pattern": "*.yourdomain.com/*",
 "zone_name": "yourdomain.com"
 }
 ]
}

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:

Terminal window
npx wrangler deploy

Verify

Test that preview URLs work:

TypeScript
// Extract hostname from request
const { hostname } = new URL(request.url);
 
const sandbox = getSandbox(env.Sandbox, 'test-sandbox');
await sandbox.startProcess('python -m http.server 8080');
const exposed = await sandbox.exposePort(8080, { hostname });
 
console.log(exposed.url);
// 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. If your worker is on a subdomain (for example, sandbox.yourdomain.com), Universal SSL won't cover the second-level wildcard *.sandbox.yourdomain.com — see the TLS caution at the top of this page for options.
  • 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.