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

Docs / Guides / Netlify

Use a free runs-at.dev subdomain with Netlify

Your Netlify site keeps building and deploying the way it does today. This guide gives it a short runs-at.dev address to share instead of the netlify.app one.

What you'll end up with

Picture a documentation site deployed on Netlify as docs-example.netlify.app. Once you are done, https://docs-example.runs-at.dev opens that same site, with a certificate that Netlify manages for the new name.

Two separate systems cooperate to make that happen:

  • Netlify hosts the site. It has to be told the full hostname it should answer for, and it handles the certificate.
  • runs-at.dev controls the DNS for your name. You save one record in the registry and it is published for you; you do not use Netlify DNS or any other DNS provider for this.

A free subdomain for Netlify needs both halves. DNS alone sends visitors to Netlify, but Netlify only serves your site once it knows the name belongs to it.

Before you start

  • A Netlify site that already works at its netlify.app address.
  • A claimed runs-at.dev name. See the quickstart if you have not claimed one. One name comes free with each GitHub account, and the administrator can grant more if you run several sites.
  • Access to the site's domain settings in Netlify.

Add the domain in Netlify

  1. In Netlify, open the site and go to its domain management settings.
  2. Add a domain and enter the full hostname, docs-example.runs-at.dev. Netlify treats it as a domain whose DNS is hosted elsewhere, which is correct: the registry runs it.
  3. Note the DNS setting Netlify shows for that hostname. For a subdomain it asks for a CNAME pointing at your site, and the value it gives is the one to use in the next step.

Note

Netlify will not create or change runs-at.dev records for you, and it does not need to. Whatever Netlify asks you to publish, you publish through runs-at.dev.

Add the DNS record

Put the target Netlify showed you in the CNAME of your record. For a subdomain this is normally your site's own netlify.app address, which is unique to your site, so copy it from your Netlify settings rather than guessing it. Enter the hostname only, with no https:// and no trailing dot.

domains/docs-example.json

"records": { "CNAME": "docs-example.netlify.app" }

Save it one of two ways:

  1. Dashboard. At runs-at.dev/manage, choose the name, open Point to my hosting, pick Netlify, paste the target and save. The field starts empty on purpose.
  2. Pull request. Fork the registry, update the records block in domains/docs-example.json, and open a pull request; it is published once merged.

The registry publishes this record as plain DNS rather than through a proxy, so Netlify sees requests for your hostname directly and can issue its certificate. A CNAME must be the only record on your name; the record reference covers what can share it.

Check the domain configuration

Go back to the domain settings in Netlify. Once the record is live, Netlify can confirm that docs-example.runs-at.dev points at the site, and its HTTPS section reports the certificate for the name. Until both are complete, the custom domain is not fully set up, even if DNS already resolves.

If Netlify shows an additional DNS step for this hostname, do what it shows. Any record it asks for is added through runs-at.dev as well.

Check that it works

  • Netlify domain settings list the name without outstanding DNS work, and HTTPS shows a certificate for it.
  • runs-at.dev/manage shows Live in the status panel, followed by your page's title, once visitors reach the site.
  • runs-at.dev/debug/docs-example (with your own name) shows the record, what DNS answers, what the name serves, and which step is missing if it is stuck.
  • From a terminal, the CNAME should name your Netlify site:
dig +short docs-example.runs-at.dev CNAME
# docs-example.netlify.app.

Common problems

Netlify does not accept the domain
Make sure you entered the whole hostname, docs-example.runs-at.dev, and not runs-at.dev alone. A hostname can only belong to one Netlify site at a time, so if it is attached to another of your sites, remove it there first.
Netlify says the DNS is not configured correctly
Compare the CNAME in your record with the target in Netlify's settings. The dashboard refuses a target with https:// or anything after the hostname, so enter the bare address. If the record was saved moments ago, it may not be published yet; the status panel shows when it is still waiting.
The dashboard says records conflict
A CNAME cannot sit beside A, AAAA, TXT or MX records, or a redirect, on the same name. Remove the others, then save the CNAME on its own.
The status panel says Not working yet
Visitors still get the runs-at.dev profile card. When the record points at a netlify.app address, that almost always means Netlify has not been told about the hostname: add it under the site's domain settings. The debug page gives the same diagnosis.
Added in Netlify, but nothing responds
The status panel reports Not answering when the target does not respond. Open the netlify.app address directly; if that fails as well, look at the site's latest deploy in Netlify.
The name opens something unexpected
The profile card means the steps above are unfinished. A different Netlify site means the CNAME names that site's netlify.app address, or the hostname was added to the wrong site in Netlify.
HTTPS has not completed
Netlify issues the certificate itself and can only do so once the hostname reaches it. Confirm DNS is correct first, then check the HTTPS section of the site's domain settings for its current state.

Warning

If you later move the site, update this record and remove the hostname from the old Netlify site, or both places will still claim the name.

Related guides