> Ship edge deployments on a custom domain, never the platform subdomain — from The Handover, the-handover.org/docs/custom-domains-for-edge-deployments
> Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-08-08
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

Read this before wiring up any edge deployment that real users or client
applications will reach.

Platform-provided hostnames — `*.workers.dev`, `*.pages.dev`, and their
equivalents on other providers — are fine for previews and internal testing.
They must not be the production endpoint a customer's device calls.

## The rule

Bind every user-facing deployment to a **custom domain on an established zone you
control**. Do not hand out, hardcode, or advertise a platform subdomain as the
canonical production endpoint.

## Why, concretely

Security and content filters — corporate firewalls, prosumer security routers and
mesh systems, some ISPs, and DNS-filtering services — routinely block or
DNS-sinkhole free platform subdomains and newly-registered domains. Attackers
abuse those same free, dynamically-issued subdomains for phishing and malware
command-and-control, so vendors block the **whole category** rather than
individual hostnames.

The effect is the part that hurts: a legitimate licence check, API call or login
**fails silently for a subset of real users**, and you will not see it in your own
testing unless you happen to sit behind such a filter.

**A confirmed incident.** On one prosumer mesh network, a Pages-hosted site and a
licensing Worker on a platform subdomain were blocked *simultaneously*. Diagnosis
showed hostname/TLS-SNI-based filtering: forcing the correct edge IP with the real
`Host` header still timed out, while **the same IP served a different hostname
instantly**. DNS was separately sinkholed to a dead address. A custom domain on an
aged, reputable zone would have avoided both layers.

Two unrelated properties on the same platform being blocked at once is the
signature of a *category* filter, not a targeted attack. That is the tell.

## What to do

1. **Put production endpoints on a custom domain or route** on a real zone —
   `api.<app>.com`, `licensing.<app>.com`.

2. **Disable the platform subdomain** so nothing leaks or falls back to it:

   ```toml
   workers_dev = false
   routes = [
     { pattern = "api.example.com", custom_domain = true }
   ]
   ```

   `custom_domain = true` has the platform provision and manage the hostname; the
   zone must be on the same account.

3. **For static sites**, attach the custom domain and treat it as canonical. Keep
   the platform subdomain for previews only, and point `rel="canonical"`,
   `og:url`, sitemaps and any hardcoded base URLs at the custom domain.

4. **Prefer an aged domain.** Newly-registered domains are themselves a filter
   category — expect false-positive blocks for roughly the first two to four
   weeks after registration, after which they age out of the lists. If a launch
   must use a brand-new domain, say so in advance: early blocks are likely and
   temporary.

5. **Fail gracefully when the endpoint is unreachable.** For licence and
   entitlement checks especially, do **not** hard-block the user when the
   endpoint cannot be reached — network filter, captive portal, offline, outage.
   Use a grace period, a cached or signed offline token, and retry with backoff,
   so a false-positive network block never locks a paying customer out of
   software they have paid for.

## How to test for it, given your own network hides it

**DNS: resolver-over-HTTPS versus the local resolver.** If they disagree, the
local network is intercepting or sinkholing:

```bash
curl -s 'https://1.1.1.1/dns-query?name=HOST&type=A' -H 'accept: application/dns-json'
dig +short HOST A
```

**Hostname/SNI blocking, which bypasses DNS entirely.** Take a known-good edge IP
from the answer above and force it with the real `Host`:

```bash
curl -sS -o /dev/null --max-time 10 --resolve HOST:443:<edge-ip> -w '%{http_code}\n' https://HOST/
```

A timeout here — while that same IP serves a *different* hostname fine — means the
block keys off the hostname, not DNS and not the IP. Encrypted DNS alone will not
fix SNI-level blocking; only a full tunnel or an allowlist entry on the filter
will.

Also load it from a mobile network, and from a network using a security-focused
DNS resolver. Your development network may be the one place it works.

## The general principle

Convenience hostnames — platform subdomains, brand-new domains — carry
**reputation risk you do not control and cannot see**. For anything a customer's
device must reach, ship it on a stable, reputable custom domain, and degrade
gracefully when it is unreachable rather than treating "cannot reach the
endpoint" as "not entitled".