Use a free runs-at.dev subdomain with Vercel

Say your project is called myproject and you have claimed myproject.runs-at.dev. At the end of this guide, opening https://myproject.runs-at.dev serves your latest production deployment, with a certificate Vercel issues for that name. Builds, previews and environment variables stay where they are.

It helps to know who controls what, because this setup spans two places:

• Your Vercel account holds the project. You tell it which hostnames it should answer for.
• runs-at.dev holds the DNS for your name. You set the record there, from the dashboard or by pull request, and the registry publishes it. You never need a DNS provider of your own.

A free subdomain for Vercel only works when both sides agree: DNS sends the name to Vercel, and your project accepts it.

• A Vercel project with at least one successful production deployment.
• A claimed runs-at.dev name. The quickstart walks through claiming one. Each GitHub account includes one free name, and the administrator can grant more if you want a separate address for another project.
• Permission to change domain settings on the Vercel project.

1. Open the project on Vercel and go to Settings → Domains.
2. Add myproject.runs-at.dev, the full name. Do not add runs-at.dev on its own: that domain belongs to the registry, and the steps below only work for your name.
3. Leave the tab open. Vercel now lists the DNS it expects for this name, and possibly a verification record as well. You will copy values from it in the next two steps.

For a subdomain, Vercel asks for a CNAME record. Vercel shows the exact CNAME target for your project in the Domains panel. Use that value as the DNS target in runs-at.dev, without a trailing dot, since the registry only accepts plain hostnames.

"records": { "CNAME": "<target shown in your Vercel Domains tab>" }

Then save it in one of two ways:

1. From the dashboard. At runs-at.dev/manage, select the name, open Point to my hosting and choose Vercel. Replace whatever the target field starts with by the value from your Domains panel, then save.
2. By pull request. Fork the registry, set the records block of domains/myproject.json, and open a pull request. It is published to DNS after it is merged.

runs-at.dev itself belongs to a different Vercel account from yours, so when you add a name under it Vercel may ask you to prove you control that specific name. If it does, the Domains tab shows a TXT record whose value begins with vc-domain-verify=myproject.runs-at.dev, followed by a token. If no such record is shown, skip this section.

The challenge does not go next to the CNAME. It goes on a label one level below your name, _vercel, which the registry stores under subdomains:

{
  "records": { "CNAME": "<target shown in your Vercel Domains tab>" },
  "subdomains": {
    "_vercel": {
      "TXT": ["vc-domain-verify=myproject.runs-at.dev,<token from Vercel>"]
    }
  }
}

On the dashboard this is a subdomain row: label _vercel, type TXT, and the whole value pasted as Vercel shows it. The registry also copies that value to _vercel.runs-at.dev, the place Vercel reads the challenge from for names under this domain. You only ever edit your own entry.

Only a challenge that names your own hostname is published. One that starts with vc-domain-verify=runs-at.dev, means the bare runs-at.dev was added in Vercel instead of your name; publishing it would hand the whole domain to one account, so the registry refuses it.

Once the record is live, press Refresh next to the domain in Vercel so it checks again.

• Vercel Domains tab. The name shows Valid Configuration once Vercel accepts the DNS and has issued the certificate.
• runs-at.dev/manage. The status panel for the name reads Live with your page title once visitors reach your project, and Not working yet while they still see the profile card.
• runs-at.dev/debug/myproject. The public diagnosis page shows the record, the live DNS answers and what the name serves, and names the specific Vercel step that is missing when the name is stuck.
• The address itself. Open https://myproject.runs-at.dev and confirm it is your production deployment.

Vercel reports an invalid configuration

Compare the CNAME in your record with the target in the Domains tab, character for character, and check it has no trailing dot or https://. If the record was just saved, it may not be published yet; the status panel on the dashboard says when it is still waiting.

Vercel asks for domain verification

Add the _vercel TXT exactly as described above. The value has to begin with vc-domain-verify= followed by your full name; a challenge for any other hostname is never published.

The dashboard rejects the record

A CNAME cannot share your name with other records, so it cannot sit beside an A, AAAA, TXT, MX or redirect. Remove those, and put the verification TXT under the _vercel subdomain rather than on the name itself. The record reference lists what can coexist.

DNS looks right, but Vercel has not verified it

When the CNAME and the TXT are both published, everything on the runs-at.dev side is done. Press Refresh in the Domains tab. If the domain was removed and added again in Vercel, it issues a new token and the old TXT no longer matches, so copy the current one.

The status panel is not Live

Not working yet means the name still shows the runs-at.dev profile card, so Vercel has not taken the name over yet; the debug page tells you which step. Not answering means nothing responded at the target, which usually points to a wrong target or a project with no production deployment.

The name opens something unexpected

If you see the runs-at.dev profile card, the steps above are not finished. If you see a different Vercel project, the name is attached to that project under Domains; remove it there and add it to the right one.

• Quickstart · claim a free subdomain first→
• Record reference · record types and subdomains→
• SEO on a runs-at.dev name · indexing a hosted site→
• GitHub Pages→
• Netlify→
• Cloudflare Pages→