All of our services support custom domains and they all work similarly. The way it works is you create two DNS records:

1. A CNAME record to send the traffic to us (or an A/AAAA if you don't have CNAME flattening)
2. A corresponding TXT record which we check to determine what content to serve the user.

The first time we receive traffic on the custom domain, a certificate will be retrieved from Let's Encrypt to enable HTTPS.

Under-the-hood we use Caddy's on-demand tls to automatically create certificates for customer domains.

Check your records #

Our CLI shows where a domain points, then looks up the TXT records for pgs, prose and tuns and tells you whether each one points at something that exists:

1ssh pico.sh dns-check meow.erock.io

meow.erock.io: CNAME pgs.sh, resolves to 129.158.37.104, 2603:c020:400a:d000:dc2d:4f96:f5d5:8a00, which is pgs.sh
_pgs.meow.erock.io: "erock-kittens" is valid, serving pgs project "kittens" of erock
_prose.meow.erock.io: no TXT record
_tuns.meow.erock.io: no TXT record
_sish.meow.erock.io: no TXT record

The check asks DNS directly, so it sees a record as soon as your DNS provider serves it. pgs and prose pick up a new record within 30 seconds of that, and a changed record within 2 minutes. tuns checks the record each time a tunnel connects.

The first line shows the CNAME, A and AAAA records and whether they lead to pgs.sh, prose.sh, tuns.sh or nue.tuns.sh. An A record on an apex domain counts as long as it uses one of our addresses.

My DNS does not support CNAME flattening #

Some DNS providers do not support CNAME flattening, which means they don't allow you to create a CNAME record for your apex domain, like "example.com".

If you want to use an apex domain without CNAME flattening, you need to get the IP addresses of the service you want to point to and then use them in an A record (for IPv4) and an AAAA record (for IPv6). You can find the current IP addresses by running host pgs.sh.

WARNING: We make no guarantees that our IP addresses will stay the same. Use at your own risk!

subdomain.yourcustomdomain.com.         300     IN      A       129.158.37.104.
_pgs.subdomain.yourcustomdomain.com.    300     IN      TXT     user-project

Can I use an ALIAS record instead of CNAME? #

Yes, it should work the exact same way.

subdomain.yourcustomdomain.com.         300     IN      ALIAS   pgs.sh.
_pgs.subdomain.yourcustomdomain.com.    300     IN      TXT     user-project

Guides #

Here are some guides for known working DNS servers. If you have another DNS server working with pico, please submit a PR!

These guides assume we are setting up pgs.sh sites with a root domain.

Cloudflare #

Cloudflare support CNAME flattening. You can read their docs on it.

CNAME   @     pgs.sh
TXT     _pgs  user-project

Namecheap #

Namecheap supports CNAME flattening through a different mechansim by using the ALIAS record. You can read their docs on it.

ALIAS   @     pgs.sh
TXT     _pgs  user-project