Custom Domains and HTTPS: The One DNS Record, Explained

TL;DR: Pointing your own domain at a hosted app usually takes one DNS record: a CNAME for a subdomain like www or app, and for a bare apex like example.com, either an A record or your DNS provider’s ALIAS/flattening feature, depending on what the host asks for. Once that record resolves to the host, an HTTPS certificate can be issued for the name, and the domain goes live.

Custom domains feel like the scary part of a deploy because half the moving pieces live somewhere else: your registrar, your DNS provider, and a certificate authority you never talk to directly. The good news is that the model is small. This guide explains what each record does, why apex domains get special treatment, how certificates get issued without you uploading anything, and how to debug a domain that won’t go live.

What does a DNS record actually do?

DNS is a lookup table. When a browser wants www.example.com, it asks the DNS servers responsible for example.com what that name points to. The answer is a record, and two record types cover almost every hosting setup:

• A record: maps a name directly to an IPv4 address. “example.com lives at this IP.”
• CNAME record: maps a name to another name. “www.example.com is an alias for edge.somehost.example; go look that up instead.”

A CNAME is usually what a host asks for, because it lets the host change the IP addresses behind its edge without you editing anything. You point at a name they control, and they keep that name current.

Which record do you need: CNAME or A?

It depends on whether your hostname is a subdomain or the bare apex of the domain.

On Candor Deploy, a subdomain such as www.example.com or app.example.com gets a CNAME. A bare apex such as example.com gets whatever record Candor gives you for it: either an A record, or a CNAME-style target that you set with your DNS provider’s ALIAS, ANAME or CNAME-flattening feature (domains and HTTPS docs). When you add a domain, Candor returns the exact record type, name and value to create. That record is the source of truth, not any blog post, including this one.

Why can’t an apex domain be a CNAME?

This trips up a lot of people. The apex of a zone (example.com itself) must carry other records, like the SOA and NS records that make the zone work, and often MX records for email. DNS rules say a name with a CNAME can’t have any other records alongside it. So the apex can’t be a literal CNAME, and hosts give you either an A record to an IP or a target to use with a flattening feature instead (domains and HTTPS docs).

Some DNS providers offer a workaround, often called CNAME flattening or an ALIAS record, which resolves a target name for you and answers with IPs. Some hosts require it for the apex, others accept it as an alternative to an A record. Either way, the simplest path is to set exactly the record your host gives you.

Do www and the apex count as one domain?

No. example.com and www.example.com are two separate hostnames as far as DNS and certificates are concerned. If you want both to work, add both. On Candor Deploy, each one you add gets its own record and its own certificate, and wildcard domains aren’t supported, so add each hostname you actually want to serve (domains and HTTPS docs).

A common setup is to treat one as canonical (say www) and have your app redirect the other to it. That keeps search engines from indexing two copies of every page and keeps cookies on one host.

How does HTTPS get set up automatically?

Modern hosts get certificates from a certificate authority using an automated challenge. The authority asks, in effect, “prove you control this hostname,” and the host proves it by answering a request on that hostname. If the answer comes back from the right place, the certificate is issued.

The important consequence: the certificate can’t be issued until your DNS points at the host. Until then, requests for your domain land somewhere else, and the challenge fails.

On Candor Deploy, every hostname an app serves, both the built-in candorhost.app URL and each custom domain, gets an HTTPS certificate that Candor provisions and renews automatically, with nothing to upload. There’s no separate TXT verification step for you either: once the record Candor gave you is in place and resolves, the certificate issues. Plain http:// requests to your domain redirect to https:// from the start (domains and HTTPS docs).

How do you add a domain, step by step?

The general flow is the same almost everywhere: tell the host the hostname, create the record it gives you, then wait for DNS and the certificate. On Candor Deploy, you add domains through the Candor MCP tools, for example by asking an AI assistant connected to Candor’s MCP server (connect Claude) to add the hostname for you (you need permission to manage domains on the project):

1. Ask your assistant to add the full hostname, like www.yourdomain.com or example.com, to an app or static site. (Databases have no public endpoint, so they don’t take domains.) This calls the add_domain tool.
2. Candor replies with the exact DNS record to create: its type, name and value, plus a note if your apex needs ALIAS or flattening.
3. Create that record at your registrar or DNS provider.
4. Check progress with the list_domains tool. It reports the DNS status (pending until the name resolves, mismatch if it resolves somewhere else, ok once it points at Candor) and the TLS status (pending until the certificate issues, then active). Either can show unknown if the check couldn’t run; look again shortly.

You can add a domain before the app’s first deploy; it’s wired up when the app first goes live. And the generated candorhost.app URL keeps working after you add a custom domain, which makes it a handy stable address for testing (domains and HTTPS docs).

Why is my domain stuck at pending?

A domain that won’t go live is almost always a DNS problem, not an app problem. Work through these in order:

• Check what the world sees. Run dig +short www.example.com (or nslookup). You should see the target from the record Candor gave you (a CNAME target for a subdomain; for an apex, the IP or the addresses your provider’s flattening resolves to). If you see your old host, or nothing, the record isn’t in effect yet.
• Check the record name. Many DNS panels append the domain automatically. Entering www.example.com in the name field can produce www.example.com.example.com. Usually you enter just www, or @ for the apex.
• Check for conflicting records. An old A record and a new CNAME on the same name will conflict, and some panels quietly keep both. Remove the old one, and remove any old AAAA record too: a leftover IPv6 address still sends some visitors to your previous host.
• Check the TTL. If the previous record had a long TTL, resolvers may keep serving the old answer until it expires. Lowering the TTL ahead of a planned move shortens that wait next time.
• Check proxies in front. If your DNS provider proxies traffic through its own network, the certificate challenge may never reach your host. On Candor Deploy, leave the record DNS-only (unproxied), not just while the certificate issues: a proxied record resolves to your provider’s addresses, so the DNS status may read mismatch.

On Candor Deploy, if a domain stays pending for hours, the docs say the record is almost always the culprit: re-check the type, name and value against the record Candor returned when you added the domain (domains and HTTPS docs).

What else can go wrong?

A few rules are worth knowing before you hit them. On Candor Deploy, a hostname can only be attached to one service across the whole platform, so adding a domain that’s already in use fails with a clear error; if it’s on another one of your services, remove it there first. You enter a full hostname, not an IP or a bare label, and removing a domain stops routing that hostname to your app while the generated URL keeps working (domains and HTTPS docs).

Outside the platform, the classic gotchas are email and expiry. Changing nameservers to move DNS can silently drop your MX records if you don’t copy them over, and a domain that lapses at the registrar takes your app down no matter how healthy it is. Turn on auto-renew.

What’s the next step?

Before you touch your registrar, open the domains and HTTPS docs, ask your Candor-connected assistant (connect Claude) to add the hostname, and copy the exact record Candor returns.