Custom Domains

Custom domains let you serve assets and API proxy requests from your own hostname (e.g., cdn.yourdomain.com) instead of the default your-tenant.cachely.io subdomain.

Custom domains are available on the Pro plan.

What you get

• Assets served from cdn.yourdomain.com/path/to/image.jpg instead of your-tenant.cachely.io/path/to/image.jpg
• API proxy works the same: cdn.yourdomain.com/~api/...
• Automatic SSL certificate provisioning
• The default your-tenant.cachely.io subdomain remains active alongside your custom domain — nothing breaks

Requirements

• Pro plan — custom domains are not available on the free plan
• One custom domain per tenant — each tenant can have one custom domain
• Subdomains only — use cdn.yourdomain.com or assets.yourdomain.com, not bare/apex domains like yourdomain.com
• Access to your DNS provider — you'll need to create a CNAME record

Setup

1. Add the domain

On the tenant detail page, find the Custom domain card. Enter your desired subdomain (e.g., cdn.yourdomain.com) and click Add.

2. Configure DNS

After adding, you'll see a DNS record table showing exactly what to create at your DNS provider:

Tips:

• Enter just the subdomain label (e.g., cdn), not the full hostname — most DNS providers append your root domain automatically
• If your DNS provider is Cloudflare, make sure the record is DNS only (grey cloud), not proxied (orange cloud)
• DNS changes usually take a few minutes but can take up to an hour

3. Verify

Once your DNS record is in place, click Check DNS. This verifies the CNAME and provisions an SSL certificate.

Possible outcomes:

• Active — DNS verified, SSL provisioned, domain is serving traffic
• Pending DNS — CNAME not yet detected. Wait a few minutes and check again
• Failed — verification failed. Check the error message and your DNS configuration

You can retry verification as many times as needed.

4. Start using it

Once active, your custom domain works identically to the default subdomain:

# Assets
https://cdn.yourdomain.com/path/to/image.jpg

# API proxy
https://cdn.yourdomain.com/~api/...

No application code changes are needed — both hostnames resolve to the same tenant and share the same cache, analytics, and configuration.

Removal

To remove a custom domain, click Remove domain and confirm. This immediately:

1. Stops serving traffic on that hostname
2. Removes the SSL certificate
3. Removes the DNS-to-tenant mapping

Your default your-tenant.cachely.io subdomain continues working. You can delete the CNAME record at your DNS provider afterwards.

When a tenant is deleted, any associated custom domain is cleaned up automatically.

Search indexing (SEO)

These settings apply only to traffic routed through Cachely. Your origin domain, such as *.vercel.app, must be configured in the origin app.

Website Proxy serves three possible hostnames for one tenant:

The Website Proxy section exposes a Search indexing control that drives X-Robots-Tag on website-proxy HTML responses. Asset and API proxy responses are never affected.

Indexable means absence of the header — Cachely never sets X-Robots-Tag: index, follow, which would override site-level <meta name="robots"> tags unnecessarily.

Recommended setup

1. Origin app — set X-Robots-Tag: noindex, nofollow (or <meta name="robots" content="noindex">) so the underlying Vercel/Netlify/Cloudflare Pages URL never gets indexed.
2. Cachely preview slug — leave the policy at Default so <slug>.cachely.io stays hidden.
3. Verified custom domain — leave the policy at Default so the canonical URL is indexable. Even if your origin app sends X-Robots-Tag: noindex, Cachely strips it on the custom-domain path so the public site is discoverable.

Behavior change in this release

The Default policy is new. Tenants upgrading from an earlier version will see two changes the first time they receive traffic after the migration:

• The Cachely preview slug now returns X-Robots-Tag: noindex, nofollow and will be progressively de-indexed by search engines.
• Upstream X-Robots-Tag: noindex is now stripped from custom-domain responses (intentional — this is what fixes the original "my canonical site is silently noindexed" bug).

If you want the old pass-through behavior on either host, set the policy to Preserve origin.

Limits

• Cachely cannot control headers on traffic that doesn't pass through Cachely. The origin domain (*.vercel.app, *.netlify.app, etc.) must be hidden in the origin app's own configuration.
• robots.txt is not currently overridden by Cachely. If your origin serves a robots.txt you want changed, edit it at the origin.
• A tenant who sets X-Robots-Tag via the security policy's Custom headers field will override the SEO policy — custom headers have precedence by design.

Troubleshooting

Domain stays in "Pending DNS"

• Verify the CNAME record exists and points to proxy.cachely.io (not your CMS origin)
• Check that the record is DNS-only, not proxied
• Wait for DNS propagation and click Check DNS again
• Some DNS providers add the root domain automatically — entering cdn.yourdomain.com as the name may create cdn.yourdomain.com.yourdomain.com. Use just the subdomain label (e.g., cdn)

Domain shows "Failed"

• The error reason is shown in the custom domain card
• Common causes: CNAME missing, CNAME pointing to wrong target, CAA records blocking SSL issuance
• Fix the DNS issue and click Retry verification

Custom domain loads but returns an error

• If you see "Tenant not found", the domain-to-tenant mapping may be missing — click Check DNS to re-trigger activation
• If you see a 525 SSL error, the SSL certificate may still be provisioning — wait a few minutes and try again

How it works

Custom domains use Cloudflare for SaaS (Custom Hostnames):

1. Adding a domain creates a Cloudflare Custom Hostname entry and begins SSL certificate provisioning
2. DNS verification confirms that your CNAME points to the proxy origin
3. On activation, a mapping is written so the edge proxy can route requests from your hostname to your tenant
4. At request time, the proxy checks the incoming hostname and resolves it to your tenant — same caching, same config, same analytics