Guides

A few practical ways to use InstantDNS without installing a large client or creating another account.

Five-minute setup

1. Create a hostname

curl https://api.instantdns.io/new

2. Save the token

TOKEN='paste-the-token-here'

3. Update the hostname

curl \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/update

Raspberry Pi / Linux cron job

You can call InstantDNS periodically and it will only change the DNS record if your address actually changed.

Create a small update script:

sudo nano /usr/local/bin/instantdns-update

Example contents:

#!/bin/sh

TOKEN='YOUR_TOKEN'

curl -fsS \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/update

Make it executable:

sudo chmod 700 /usr/local/bin/instantdns-update

Then run it every five minutes:

crontab -e

*/5 * * * * /usr/local/bin/instantdns-update >/dev/null 2>&1

The example above stores the token in a local script. Make sure the file is readable only by the intended user.

Update all devices together

If your parent and child records should all follow the same connection, use:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/update?scope=all"

The default update behaviour is intentionally safer: without scope=all, only the parent hostname changes.

Multiple devices

Create a camera hostname:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/new?name=camera"

Create a NAS hostname:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/new?name=nas"

Update only the camera:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/update?name=camera"

Force IPv4 or IPv6

curl can force which network family reaches the API:

# Update the A record
curl -4 \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/update

# Update the AAAA record
curl -6 \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/update

Check DNS

dig your-hostname.instantdns.io A
dig your-hostname.instantdns.io AAAA

Or test through Cloudflare's recursive resolver:

dig @1.1.1.1 your-hostname.instantdns.io A
dig @1.1.1.1 your-hostname.instantdns.io AAAA

A note about ports

DNS maps hostnames to IP addresses. It does not normally specify your web application's TCP port.

If you run several web services on one IP, use a reverse proxy such as Caddy or nginx to route requests by hostname, or include the port in the URL where appropriate.