Connect a custom domain
Serve a website from a subdomain you own, such as www.example.com, with a certificate Benchy manages.
Before you start
- Custom domains need a paid plan. See Plans for how many.
- Use a subdomain you control, such as
www.example.com. A bare domain such asexample.comcan’t point at benchy.site: redirect it towwwat your registrar or DNS provider. - You need to be able to add DNS records where the domain’s DNS is run.
Add a domain
In the Domains section of the website’s page in Studio, enter the domain under Custom domains and choose Add. A person with Can edit does this, or an agent whose key or connection can make changes across the workspace; a Publish websites key can’t, and neither can Benchy.
Benchy refuses wildcards, IP addresses, bare domains, names mixing alphabets, and domains belonging to Benchy or other hosting platforms, such as vercel.app or workers.dev, saying which rule the domain broke.
Create the two records
Create both records Benchy shows at your DNS provider:
| Type | Name | Value |
|---|---|---|
| CNAME | www.example.com | domains.benchy.site |
| TXT | _benchy-challenge.www.example.com | The value Benchy shows for this domain |
- The CNAME sends visitors to Benchy. The TXT record proves the domain is yours; a CNAME alone doesn’t, because one left behind by someone else would let a stranger claim the name.
- The TXT value is new each time the domain is added, so an old record proves nothing.
- If the domain serves a site elsewhere today, create the TXT record first and switch the CNAME when you’re ready. The domain can’t become active until the CNAME points at Benchy.
What each state means
| State | What it means |
|---|---|
| Waiting for DNS | Benchy is looking for the TXT record — often at first, then hourly, for up to 3 days. The row says what the last check found: nothing yet, a value that doesn’t match, or DNS that didn’t answer |
| Waiting for the certificate | The domain is proven yours and its certificate is being issued, usually within minutes. If another website is still letting go of the domain, it waits for that |
| Certificate blocked | The domain’s CAA records don’t allow the authority issuing its certificate. The row names the authority and the CAA record to add beside yours |
| Active | The domain serves this website |
| Primary | Active, and the website’s primary address. See below |
| Not pointing here, Can’t reach it | Active, but Benchy can’t see the CNAME point at domains.benchy.site, or can’t reach the domain. It still serves whoever reaches it, but it can’t be the primary address |
| Not serving | Active, but over the plan’s cap or in a workspace on hold. It serves again when the plan or the hold allows |
| Failed | The records didn’t appear or match within 3 days, the certificate couldn’t be issued, or the TXT record went missing. The row says which and what to do. A certificate that couldn’t be issued is asked for again every 6 hours for a week |
| Removing | It stops serving within a few minutes, then the row goes |
Check now looks again within 2 minutes, up to 4 times an hour. Every message a row can show is under Custom domain messages.
Only the first website to prove a domain gets it; adding one proven elsewhere says “That domain is connected to another website, or is still being removed.” A failed domain stays listed for a week, so you can read why.
Screenshot: the two records to create, with the value to copy beside each.
Keep the TXT record
Benchy checks every active domain’s TXT record daily to know it is still yours. If it goes missing, the row warns you with the date the domain will stop serving; after 3 days it stops. Put the record back and it serves again within about 6 hours.
What the domain serves
The website’s live version, never a preview; taking the website offline, or a suspension, applies to the domain too. Benchy issues and renews the certificate and sets nothing for your other subdomains.
Your domain as the primary address
A website has one primary address, the one it is shared at. It is name.benchy.site until a custom domain is Active and Benchy has seen its CNAME point at Benchy; then the oldest such domain is primary. Make primary on another domain’s row, or on the name.benchy.site row, picks that one instead.
- Visitors to the website’s other addresses get a permanent redirect to the primary, keeping the page and query.
- Never redirected: previews, form entries,
/_benchy/and/.well-known/. - A website published from a canvas has its address written into its pages (canonical link, link previews, sitemap). Publish the canvas again after the primary changes; until then every address serves it without a redirect.
- A website built as files redirects as soon as the domain is primary. Set its canonical link and sitemap yourself.
- Benchy checks each domain’s DNS about hourly. A primary domain that stops pointing at Benchy stops being primary until it points back, and the person who connected it gets an email.
- A domain behind a proxy or CDN that hides its CNAME, such as Cloudflare’s orange cloud or an ALIAS record, still serves the website but never becomes primary. Set the record to DNS only.
How many you can have
The cap is per workspace, across its websites, and waiting and failed domains count until removed. On a plan with fewer domains, the oldest keep serving up to the cap and the rest show Not serving until the plan allows. While the workspace is on hold after a suspension, none serve. A workspace can add 10 domains an hour and 30 a day; removing is never limited.
Remove a domain
Choose Remove on the domain’s row and confirm. It stops serving within a few minutes; then you can delete its DNS records. Anyone who proves it can then add it again, with a new TXT value.