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

Docs / Quickstart

Get a free subdomain in four steps

Sign in with GitHub, pick a name, claim it, and point it at your project. This page takes you from nothing to a working yourname.runs-at.dev, and covers what to do when you want more than one.

Before you start

A runs-at.dev name is a subdomain of runs-at.dev, not a domain registered to you. If you are unsure which you need, read free subdomain vs free domain first. To claim one you need:

  • A GitHub account that is at least 30 days old and has at least one public repository. Both are checked when you claim, using the details GitHub provides at sign-in.
  • A free domain slot. Every eligible account includes one; if you already hold a name, another one needs an extra slot granted by the administrator.

Names are 2 to 32 characters long and use lowercase letters, digits and hyphens. A name cannot begin or end with a hyphen, cannot have two hyphens as its third and fourth characters, and some names are reserved.

Sign in with GitHub

On the homepage, use the Sign in with GitHub button. GitHub asks you to approve read access to your public profile, then sends you back to runs-at.dev signed in. Your GitHub login becomes the owner of every name you claim, and the same sign-in is how you manage them afterwards.

You can check whether a name is free before signing in. You only need to be signed in for the claim itself.

Check and claim a name

  1. Type the name you want into the box on the homepage.
  2. Read the line under it. It tells you when a name is available, when it is already claimed, when it is reserved, and when it breaks one of the naming rules.
  3. Press Claim it while you are signed in.

A successful claim ends with a message that the name is yours. Behind that, runs-at.dev adds a small public record for your name to the registry, owned by your GitHub account:

domains/yourname.json

{
  "name": "yourname",
  "owner": { "github": "your-github-login" },
  "claimedAt": "<when you claimed it>",
  "records": {}
}

With no records set, the name shows a profile card built from your GitHub account, so it is useful from the moment you claim it. If the claim is refused, the message says why: for example that the account is too new or has no public repository yet, or that you have used all your domain slots.

Point it at your hosting

Open runs-at.dev/manage and pick the name. From there you can keep the profile card, send visitors to another address with a redirect, point the name at a site you host elsewhere, or add DNS records yourself. runs-at.dev runs the DNS for your name, so you do not need a DNS provider of your own.

For the most common hosts, follow the guide for yours:

Each record type and which ones can be combined is covered in the DNS record reference.

Check that it works

  • On /manage. Each name has a status panel. Live means visitors get what you set up, Redirecting means they are being sent on to your redirect address, Not working yet means they still see the profile card, and Not answering means nothing responded where the name points.
  • On the debug page. runs-at.dev/debug/yourname shows the record, what DNS is answering right now and what the name serves, and names the missing step when something is stuck. It is public, so you can share the link when asking for help.
  • From a terminal. A DNS lookup shows what your name currently points at, for example:
dig +short yourname.runs-at.dev CNAME

Managing more than one domain

Each eligible GitHub account includes one domain. If you need more, for separate projects for example, the administrator can grant additional domain slots to your account. Slots are permission to claim; you still claim each extra name yourself, the same way as the first.

Every name your account owns appears on runs-at.dev/manage under one sign-in. The page shows how many domains you have used out of how many you are allowed, lets you switch between your names, and links to claiming another one while a slot is free. Releasing a name frees its slot again.

Claiming through a pull request

If you would rather use Git than the website, you can claim a name by pull request against the public registry. The same rules apply as on the website.

  1. Fork the registry and add one file, domains/yourname.json, shaped like the record above with your own GitHub login as the owner.
  2. Open a pull request that changes only that file. Automated checks confirm the name, your account's eligibility and that you have a free slot.
  3. While the pull request is open, a slot is held for the name so it counts against your allowance straight away. The checks run again once that hold is in place.
  4. When the pull request is merged, the name is yours. If it is closed without being merged, the held slot is released.

Note

Claiming on the website is quicker: the name is written for you with no pull request to wait on.

What to do next