runs-at.dev
runs-at.dev // documentation

Docs / Guides / Cloudflare Pages

Use a free runs-at.dev subdomain with Cloudflare Pages

Keep the project deploying on Cloudflare Pages and give it a friendlier address on runs-at.dev than the one ending in pages.dev.

What you'll end up with

Take a Pages project published at docs-example.pages.dev. After this guide, https://docs-example.runs-at.dev loads the same deployment, and Cloudflare Pages looks after the certificate for the new hostname.

Responsibility is split in two, and it helps to keep them apart:

  • Cloudflare Pages, in your own Cloudflare account, builds and serves the project and decides which custom hostnames it answers for.
  • runs-at.dev owns the DNS for every name under it. You describe the record in the registry and it is published for you. runs-at.dev happens to run its own DNS on Cloudflare too, but that is a separate account: you never need access to it, and you do not add a zone to yours.

Getting a free subdomain for Cloudflare Pages working means telling Pages about the name and pointing the name at Pages. Either one alone is not enough.

Before you start

  • A Pages project whose pages.dev address already loads correctly.
  • A claimed runs-at.dev name; the quickstart covers claiming. Each GitHub account includes one name for free, and the administrator can grant extra slots if you need more.
  • Access to the Pages project in your Cloudflare dashboard.

Add the domain in Cloudflare Pages

  1. Open your Pages project in the Cloudflare dashboard and find its Custom domains tab.
  2. Set up a custom domain and enter the full hostname, docs-example.runs-at.dev.
  3. Because the parent domain is not a zone in your account, Cloudflare asks you to create the DNS record at the provider that runs it. Read the record it shows; that is what you will publish through runs-at.dev next.

Note

Do this step first. A DNS record pointing at pages.dev does not by itself make Pages serve your hostname; Pages has to have the name listed under the project's custom domains.

Add the DNS record

For a subdomain on another provider, the record is a CNAME to the project's pages.dev address. That address belongs to your project, so use the exact value from your Cloudflare dashboard, as a bare hostname with no https:// and no trailing dot. If the dashboard shows something different for your setup, the dashboard wins.

domains/docs-example.json

"records": { "CNAME": "docs-example.pages.dev" }

Then save the record:

  1. On the dashboard: at runs-at.dev/manage, select the name, open Point to my hosting, choose Cloudflare Pages, paste your pages.dev address into the empty field and save.
  2. By pull request: fork the registry, put the CNAME in domains/docs-example.json, and open a pull request. The record is published after it merges.

runs-at.dev publishes the record as DNS only, without its own proxy in the way, so traffic for your hostname goes straight to Pages and Pages can issue the certificate for it. A CNAME has to be alone on its name; see the record reference for what can be combined.

Check the custom-domain status

Return to the project's Custom domains tab. Cloudflare lists each hostname with its status, and the entry for docs-example.runs-at.dev moves on once Cloudflare can see the CNAME and has set up the certificate. Until that entry is finished, treat the setup as incomplete even if the hostname already resolves.

If Cloudflare asks for any further DNS record for this hostname, create it through runs-at.dev in the same way.

Check that it works

  • Custom domains tab: the hostname shows as active for the project.
  • runs-at.dev/manage: the status panel for the name reads Live, with your page's title, when visitors reach the project.
  • runs-at.dev/debug/docs-example (your own name in place of the example): the public diagnosis page, listing the record, the DNS answers, what the name serves and what is missing.
  • In a terminal, the CNAME should name the project:
dig +short docs-example.runs-at.dev CNAME
# docs-example.pages.dev.

Common problems

Pages will not accept the custom domain
Enter the complete hostname, docs-example.runs-at.dev, never runs-at.dev on its own. Check the name is not already attached to another Pages project.
The DNS record is wrong
The CNAME must match the project's pages.dev address exactly. The runs-at.dev dashboard refuses a target that includes https:// or a path, and one that points at your own runs-at.dev name.
Records conflict
A CNAME cannot share your name with A, AAAA, TXT or MX records or with a redirect. Remove the others before saving it.
DNS looks right but Pages does not pick it up
Make sure the hostname is listed under the project's custom domains, not just pointed at pages.dev. For a pages.dev target, the debug page reports exactly this: DNS reaches the platform, but nothing there is configured to answer for your name.
The status panel says Not working yet
Visitors are still getting the runs-at.dev profile card, so the record has not taken effect yet or was not saved. Confirm it on the dashboard; the status panel shows when a change is still waiting to be published. Not answering instead means nothing responded at the target.
The hostname opens something unexpected
The profile card means the setup is not finished. Another site means the CNAME names a different pages.dev address, or the hostname is attached to a different Pages project.
The custom domain or HTTPS is still pending
Pages issues the certificate itself and can only finish once it sees the CNAME. Get DNS right first, then follow the status Cloudflare shows on the Custom domains tab.

Warning

When you move the project or delete it, update or remove this record too, and remove the hostname from the old Pages project.

Related guides