Sandbox SDK docs improvement

[irvinebroque]

Existing documentation URL(s)

https://developers.cloudflare.com/sandbox/

What changes are you suggesting?

Specific documentation changes

These are concrete edits to ship to the two docs pages that cover production preview URLs. Each change is scoped to a specific page and section, written as a prompt you can hand to a docs agent.

Changes to Deploy to Production

Source file: src/content/docs/sandbox/guides/production-deployment.mdx

1. Split "Create Wildcard DNS Record" into apex vs. subdomain paths

The current "Create Wildcard DNS Record" section only shows one example: a * A record. If the Worker runs on a subdomain (e.g., sandbox.yourdomain.com), the DNS record name must be *.sandbox, not *. The current page doesn't mention this.

Change: Replace the single DNS record instruction with a tabbed or branching layout — one for apex, one for subdomain. For the subdomain tab, show:

• Type: A
• Name: *.sandbox (where sandbox matches your Worker's subdomain)
• IPv4 address: 192.0.2.0
• Proxy status: Proxied (orange cloud)

Add a sentence explaining that if your Worker is deployed at sandbox.yourdomain.com, preview URLs become {port}-{id}-{token}.sandbox.yourdomain.com, so the wildcard record needs the *.sandbox name to match them.

2. Split "Configure Worker Routes" to match the DNS branching

The route example currently shows *.yourdomain.com/*. For a subdomain deployment, the route must be *.sandbox.yourdomain.com/*.

Change: Add a subdomain variant alongside the existing apex example:

// Apex deployment
"routes": [{ "pattern": "*.yourdomain.com/*", "zone_name": "yourdomain.com" }]

// Subdomain deployment (Worker on sandbox.yourdomain.com)
"routes": [{ "pattern": "*.sandbox.yourdomain.com/*", "zone_name": "yourdomain.com" }]

3. Move the TLS callout into the subdomain setup path, not just the top of the page

The "Subdomain depth matters for TLS" callout currently sits at the top of the page, before the setup steps. A developer following the steps linearly can miss it or not realize it applies to them until after deploying.

Change: Keep the existing callout at the top, but also add a visible warning inside the subdomain branch of the DNS/route setup that says:

You also need a TLS certificate covering *.sandbox.yourdomain.com. Universal SSL does not cover second-level wildcards. See the options at the top of this page, or use Advanced Certificate Manager ($10/month) to order one through the dashboard.

This puts the TLS action item directly next to the step where it matters.

4. Add "HTTPS inside containers" to the Troubleshooting section

The troubleshooting section has no entry for the error Connecting to a container using HTTPS is not currently supported. A developer hitting this error has no doc to reference.

Change: Add a new troubleshooting bullet:

"Connecting to a container using HTTPS is not currently supported": Your service inside the sandbox is using HTTPS (for example, Node.js https.createServer() or a framework with --https enabled). Configure it to serve plain HTTP instead. Cloudflare terminates TLS at the edge, so the browser connects over HTTPS — but the internal connection to your container is already secure and uses HTTP. This is the same model as running behind any reverse proxy. If your framework checks the protocol and redirects HTTP to HTTPS, configure it to trust the proxy (for example, app.set('trust proxy', 1) in Express).

5. Add "Error 1016 / 522 after deploying" to the Troubleshooting section

Developers hitting these errors after changing DNS records or routes have no Sandbox-specific guidance.

Change: Add two troubleshooting bullets:

Error 1016 (Origin DNS error): Cloudflare can't resolve the origin for the requested hostname. Verify your wildcard DNS record exists and is proxied (orange cloud). If your Worker runs on a subdomain like sandbox.yourdomain.com, the DNS record name must be *.sandbox, not *. Wait 30-60 seconds for propagation after creating the record.

Error 522 (Connection timed out): Cloudflare timed out reaching the origin. This often happens temporarily after creating or changing DNS records and routes. Wait 60 seconds and retry. If it persists, verify proxyToSandbox() is called first in your Worker's fetch handler — if it's not handling the request, Cloudflare tries to reach the 192.0.2.0 origin, which times out.

6. Add a "How requests flow" section before Setup

Developers who don't understand the request path can't debug problems. The current page jumps straight to DNS configuration without explaining why wildcard DNS and routes are needed.

Change: Add a short section after the introductory paragraph and before Prerequisites:

How preview URL requests flow

When a browser visits a preview URL like https://8080-my-sandbox-abc123.yourdomain.com:

1. DNS: The wildcard record (*.yourdomain.com) resolves the hostname to Cloudflare's proxy.
2. TLS: Cloudflare terminates TLS at the edge using your domain's certificate. The browser gets a secure HTTPS connection.
3. Worker route: The wildcard route (*.yourdomain.com/*) matches the request and sends it to your Worker.
4. proxyToSandbox(): Your Worker calls proxyToSandbox(), which extracts the sandbox ID and port from the hostname and routes the request to the correct Durable Object.
5. Container: The Durable Object forwards the request to the service inside your container over an internal connection (HTTP — TLS is not needed because the transport is already secure within Cloudflare's network).

Each step can fail independently: DNS can resolve but TLS can fail (certificate doesn't cover the hostname), or TLS can succeed but the route doesn't match (request reaches the wrong Worker or no Worker at all).

Changes to Preview URLs

Source file: src/content/docs/sandbox/concepts/preview-urls.mdx

7. Add "How requests are proxied" section after "Request Routing"

The "Request Routing" section shows the proxyToSandbox() code but describes the flow only as "Browser → Your Worker → Durable Object (sandbox) → Your Service." This is too terse to help someone debugging TLS or HTTPS issues.

Change: Replace the one-line description with:

Request flow: Browser → HTTPS → Cloudflare edge (TLS termination) → Worker → Durable Object → HTTP → Container

Cloudflare terminates TLS at the edge. Your service inside the container receives plain HTTP requests over an internal connection — no TLS is needed because the transport between the Durable Object and the container VM is already secure. Your service should bind on HTTP, not HTTPS.

8. Add "HTTPS inside containers" to the "What Does Not Work" list

The current "What Does Not Work" section lists TCP/UDP, custom protocols, port range, and port 3000. It does not mention that the service inside the container must serve HTTP, not HTTPS.

Change: Add a bullet:

• HTTPS servers inside the container (the internal connection uses HTTP — Cloudflare handles TLS at the edge, so your service should serve plain HTTP on the exposed port)

9. Add "Container HTTPS error" to the Troubleshooting section

The troubleshooting section on this page has no entry for the HTTPS container error.

Change: Add a new subsection:

Container HTTPS Error

If you see: Connecting to a container using HTTPS is not currently supported; use HTTP instead

Your service inside the sandbox is serving HTTPS. Configure it to serve HTTP instead. Cloudflare handles TLS between the browser and the edge — the connection from the Durable Object to your container is internal and already secure.

Common causes:

• Node.js using https.createServer() instead of http.createServer()
• A framework started with an HTTPS flag (for example, --experimental-https in Next.js)
• A framework redirecting HTTP to HTTPS (configure it to trust the proxy — for example, app.set('trust proxy', 1) in Express)

10. Add DNS wildcard note to "Security" section

The Security section says "HTTPS in production — All traffic is encrypted with TLS. Certificates are provisioned automatically for first-level wildcards (*.yourdomain.com). If your worker runs on a subdomain, see the TLS note in Production Deployment."

The phrase "certificates are provisioned automatically" is misleading for subdomain deployments — Universal SSL does not auto-provision certs for second-level wildcards. Developers reading only this page (not the production deployment guide) would assume TLS just works.

Change: Rewrite the HTTPS bullet to:

HTTPS in production — All traffic between the browser and Cloudflare is encrypted with TLS. If your Worker runs on the apex domain, Cloudflare's Universal SSL covers *.yourdomain.com automatically. If your Worker runs on a subdomain (for example, sandbox.yourdomain.com), you need a certificate covering *.sandbox.yourdomain.com — Universal SSL does not cover second-level wildcards. See Production Deployment for options including Advanced Certificate Manager ($10/month).

Additional information

No response

[irvinebroque]

/bonk please implement docs changes based on the context in this issue. As you make changes, please think critically about the accuracy of these changes, cross-referencing the Cloudflare Docs. When you are done, please flag any things you are uncertain about, or think may be unsubstantiated and need human review.

[ask-bonk]

Created PR #28382

github run

[github-actions]

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify long-standing issues in our repo (and not used to auto-close issues).