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, the review before a project's first deploy has an Address card with two choices: the free test address (shown in full), or your own domain, where you type the name and press Add. Later, the same card is on the project's Settings tab. 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. On a project that has not deployed yet it is only saved, and goes live on the first deploy. 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. A wildcard record such as *.example.com does not change this. A name that a wildcard itself answers, like app.example.com under *.example.com, gets no www redirect, so the wildcard does not cost a certificate for every such name; list www.app.example.com yourself if you want it.

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.

When the certificate authority rate-limits a domain

Let's Encrypt issues at most 50 certificates a week for one registered domain, such as example.com with every name under it, and 5 a week for the same exact name. ox gets one certificate per name: each domain, each www. redirect, each staging copy and each branch preview under your preview domain. It has no wildcard certificate. A busy week of previews, or many sites under one domain, can reach the limit.

Then the name has no HTTPS for a while. ox doctor and the server page say the certificate authority rate-limited shop.example.com; it retries automatically after 2026-10-09 10:20 UTC. Caddy asks again by itself and gets the certificate once the limit allows it, and the fix line says which limit it was. For the 50 a week per domain or the 5 for one name, there is nothing to fix but the wait. Let's Encrypt also limits a name that failed validation too often, which is what a name that does not point at your server yet runs into: then fix its A record (see its row on the Domains card) and Caddy gets the certificate once that limit lifts. To stay under the weekly limits, use fewer distinct names under one domain, and put the preview domain on a domain of its own, so previews never use up production's certificates.

What each domain status means

While the Domains card is open, ox checks each name at a public DNS resolver again once its last answer is 30 seconds old, 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.