Add a custom domain to your app with automatic HTTPS

To add a custom domain with HTTPS, create an A record for the name that points at your server's IP, then add the name on the project's Settings tab or with ox domains <project> add <name>. Caddy on your server gets a free certificate for it and renews it by itself, so there is nothing to install or renew by hand.

Add a custom domain

Create the DNS record first (the next section), then add the name to ox. In the dashboard, open the project's Settings tab, type the name in the Domains card and press Add. From a terminal:

ox domains shop add shop.example.com --wait

Adding a domain saves it and redeploys the app so the server starts serving the name. ox domains shop remove shop.example.com takes one off again.

You can also list names in ox.toml with domains = ["shop.example.com"] (top-level keys). For production, the names in ox.toml come first and the ones you add in ox come after; the list marks each name from ox.toml, and you remove those by editing the file. Staging and previews never take production's ox.toml names.

Point the domain at your server with an A record

At your DNS provider, create an A record for the name with your server's IP address as the value. The Domains card shows it: Then create an A record pointing at <ip>, and an AAAA record when the server has an IPv6 address. ox domains shop prints the same:

Point each domain's A record at 203.0.113.7.

For a whole site at the root, like example.com, the record's name is usually @. When www.example.com also points at the server, ox sends it to example.com with a permanent redirect; list www.example.com as a domain yourself if you want it served instead.

How the HTTPS certificate is issued

Caddy, the web server ox puts on your server, gets a free certificate for each domain and renews it before it runs out. You do nothing. To prove the name is yours, the certificate authority connects to the name on ports 80 and 443, so the name must already point at your server. Until it does, there is no certificate, and Caddy tries again by itself.

That is why the record comes first. If you, or ox's check, look the name up before the record exists, a DNS resolver can remember the answer no such name for a while, often from a few minutes up to an hour, and keep giving it after you create the record. Creating the record before anyone looks the name up avoids that wait.

Ports 80 and 443 must be open to the internet. If your cloud provider has a firewall in front of the server, open them there. Staging and branch previews can get HTTPS names too, under a preview domain.

What each domain status means

ox checks each name at a public DNS resolver about every 30 seconds, and the row shows what it found:

The row turns green by itself once the record resolves; you do not have to add the domain again.

If the custom domain does not work

• The row stays on waiting for DNS: check the record's name and type at your DNS provider. A new record can take a while to reach every resolver, longer if the name was looked up before it existed.
• points elsewhere: the name still points at an old host. The row says It resolves to <ip>, not this server. with the record to set.
• No certificate behind Cloudflare: a name two levels deep, like a.b.example.com, is not covered by Cloudflare's free certificate. Set the record to DNS only, so your server gets its own, or add a certificate for it in Cloudflare.
• The browser warns about the certificate: the name has pointed at the server only for a moment, or ports 80 and 443 are closed in a firewall in front of it. Open them and give Caddy a minute.

Troubleshooting has the same steps in short.