Custom domains

A folder can be served on any number of hostnames you own, such as www.example.com or docs.example.com. Add the hostname, point a CNAME record at the folder, verify it, and permahost.io serves the folder there with HTTPS.

LLM-friendly version (Markdown): https://permahost.io/docs/domains.md

1. 01AddAdd the hostname to a folder. It starts as pending and shows the CNAME target.
2. 02PointCreate the CNAME record at your DNS provider.
3. 03VerifyOnce the record resolves, the domain turns active and gets a certificate.

Add a domain

With the CLI, the web app (the globe button on a folder) or the API:

$ permahost domain add --id k7q2m9xa3bd www.example.com
Added www.example.com to folder k7q2m9xa3bd. Create this DNS record:

  www.example.com  CNAME  k7q2m9xa3bd.file.permahost.io

then run "permahost domain verify --id k7q2m9xa3bd www.example.com".

A pending domain reserves nothing and costs nothing: only a verified domain is unique, so nobody can squat a hostname by adding it first.

The DNS record

Take the target from domain add or domain ls rather than writing it by hand. Apex domains such as example.com can't hold a CNAME record, so use a subdomain such as www. If your DNS provider proxies traffic (Cloudflare's orange cloud), turn the proxy off for this record, so the CNAME is visible to public resolvers and the certificate can be issued.

Verify

$ permahost domain verify --id k7q2m9xa3bd www.example.com
www.example.com is active and serves folder k7q2m9xa3bd.
$ permahost domain ls --id k7q2m9xa3bd
ID           HOSTNAME         STATUS  CNAME TARGET               LAST ERROR
3hVt9qXc2Lm  www.example.com  active  k7q2m9xa3bd.file.permahost.io

The server looks the record up directly at public resolvers (1.1.1.1 and 8.8.8.8), so a record cached elsewhere doesn't matter. You don't have to run verify yourself: pending domains are checked every 5 minutes for 7 days. Running it checks right away. Until the record matches, verify fails and domain ls shows the last error.

HTTPS

When a domain turns active, a Let's Encrypt certificate is obtained for it in the background (TLS-ALPN-01). Until it arrives a browser may show a certificate warning. The certificate renews on its own.

Cost

A custom domain costs 500 credits to set up plus 500 credits a month, charged when its CNAME record is verified. Each renewal then charges the month for every active domain. If the account can't pay when the record is verified, the domain stays pending. See credits.

Remove

$ permahost domain rm --id k7q2m9xa3bd www.example.com
Removed www.example.com from folder k7q2m9xa3bd.

Removing a domain stops serving the folder there and stops its monthly charge from the next renewal. Delete the CNAME record too.

Troubleshooting