# Add a custom domain to your app with automatic HTTPS

Add a custom domain to your app: create the A record, add the name in ox, and Caddy gets and renews the HTTPS certificate. What each domain status means.

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.

You create an A record that points the name at your server. While the Domains card is open, ox looks the name up again once its last answer is 30 seconds old, and the card shows what it found, from **checking DNS…** to **HTTPS on**. Caddy on your server gets the certificate over ports 80 and 443 and renews it by itself.

## 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:

Add a domain:

```sh
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](https://console.t66.sorv.dev/docs/config#top-level)). 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:

ox domains shop:

```text
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](https://console.t66.sorv.dev/docs/operate/previews#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](https://console.t66.sorv.dev/docs/operate/domains#states)) 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](https://console.t66.sorv.dev/docs/operate/previews#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 says | It means |
| --- | --- |
| **checking DNS…** | The first lookup has not come back yet. |
| **waiting for DNS** | The name has no address yet. Create the A record, or wait for it to spread. |
| **points elsewhere** | The name has an address, but not your server's. Change the record. |
| **HTTPS on** | The name points at your server, so the server can get its certificate. |
| **Cloudflare** | Cloudflare's proxy is in front, which hides where the name points. In Cloudflare, set its A record to your server's IP. |
| **No certificate** | Cloudflare's proxy has no certificate for the name. |

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](https://console.t66.sorv.dev/docs/troubleshooting#domain-not-working) has the same steps in short.

Last updated 2026-10-10. The page as HTML: https://console.t66.sorv.dev/docs/operate/domains