Getting started

legitdns gives your home network a stable name. Your connection's address changes whenever your provider feels like it; your hostname does not. Devices and scripts report the new address, and the name follows.

1. Create your account

Register on legitdns.com with an email address and a password (at least 12 characters, with a letter and a number). We email you a verification link, valid for 24 hours; you cannot sign in before you click it.

Your email is used for account messages (verification, password resets, warnings) and may be used for marketing later. That is stated in the privacy policy before you sign up.

2. Claim a hostname

In the panel, choose "New hostname":

• Pick a domain from the list we offer. Your hostname is one label under it.
• Type the label: letters, digits, hyphens. Some labels are reserved (www, mail) and cannot be claimed.
• Free accounts currently start with 3 hostnames.

Examples in these docs use sample names like mypi.pihome.example; the panel shows the real domains.

3. Save your token

The panel shows the hostname's update token exactly once, at creation. Copy it somewhere safe. We store only a scrambled copy, so nobody - including us - can show it again. If you lose it, generate a new one in the panel; the old one stops working immediately.

The token is the password for this one hostname: it cannot open your account or touch other hostnames. Tokens has the details.

4. Send your first update

One command is the fastest test. Leave the address out, and we publish the address the request comes from:

curl -H "Authorization: Bearer YOUR-TOKEN" \
  "https://legitdns.com/api/v1/update?hostname=mypi.pihome.example"

A good answer:

{"status": "good", "reason": "ok", "hostname": "mypi.pihome.example", "changed": true, "records": {"A": "192.0.2.44", "AAAA": null}, "previous": {"A": null, "AAAA": null}}

(The A record shows the address the request came from.) For hands-free updates, set up a client, a router, or the Windows scheduled script next - that is the normal way to run things.

Check it worked

dig +short mypi.pihome.example
dig +short AAAA mypi.pihome.example

Or check the history page in the panel: every attempt is listed with the address it set and whether it worked. DNS answers are cached, so a change can take up to about five minutes to show everywhere.

Then reach it from outside

A working hostname is only half the job. To connect to the device from outside your home, the device needs a service listening, your router needs a port forward, and your connection needs a genuinely public address. Reaching your device from outside walks through all three - including the shared-address setups (CGNAT) where connections from outside cannot reach you at all, and how to tell if that is your situation.

Which address gets published?

With no address in the request, the one the request came from. /checkip shows you that address:

curl https://legitdns.com/checkip

Call it over IPv4 for your IPv4 address, over IPv6 for your IPv6 address. The scripts and routers in these docs rely on this. The API page documents sending an explicit address instead, for publishing a different one.

Keeping your account

If your account has no activity for six months - no sign-in, no updates - we send warning emails first (about a month before, and again about a week before), then withdraw your hostnames: they stop resolving, and the account may then be closed and its hostnames freed for others to register. Signing in, or keeping a hostname updated, counts as activity and restarts the clock - and if you sign in while your hostnames are withdrawn, they come back. The exact terms are in the EULA.

Next: Update methods, or straight to the client guides. On a Mac, the macOS page sets up an updater that runs itself. If your provider rotates an IPv6 prefix, see IPv6 prefix mode.