# Connect a custom domain

> Serve a website from a subdomain you own, such as www.example.com, with a certificate Benchy manages.

Canonical: https://benchy.world/docs/websites/custom-domains
Last updated: 2026-10-09

## Before you start [#before]

- Custom domains need a paid plan. See [Plans](https://benchy.world/docs/websites/plans-and-limits#plans) for how many.
- Use a subdomain you control, such as `www.example.com`. A bare domain such as `example.com` can’t point at benchy.site: redirect it to `www` at your registrar or DNS provider.
- You need to be able to add DNS records where the domain’s DNS is run.

## Add a domain [#add]

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 [#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 [#states]

| 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](#primary) |
| 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](https://benchy.world/docs/websites/troubleshooting#domains).

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.

## Keep the TXT record [#keep-txt]

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 [#serving]

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 [#primary]

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 [#plans]

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 [#remove]

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.