Connect a custom domain

Before you start

• Custom domains come with a paid plan. See Plans for how many.
• Use a subdomain you control, such as www.example.com or shop.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 for the domain, at the company that runs its DNS.

Add a domain

On the website’s page in Studio, under Custom domains, enter the domain in Domain and choose Add. From a terminal or an agent:

benchy site domain add olive-prints www.example.com   # prints the two records
benchy site domain list olive-prints                    # each domain's state
benchy site domain remove olive-prints www.example.com

The MCP tools are site_domain_add, site_domain_list and site_domain_remove. Connecting a domain decides where your website answers, so a person does it: someone with Can edit in Studio, or a key or app that can change the whole workspace. A key that only publishes websites can’t, and neither can Benchy.

Benchy refuses a wildcard, an IP address, a bare domain, a public suffix, a name that mixes alphabets, and domains that belong to Benchy or to hosting platforms such as vercel.app or workers.dev. The message says which rule the domain broke.

Create the two records

Benchy shows two records with Copy buttons. Create both at your DNS provider:

• 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 value is new every time the domain is added, so a record left from an earlier website proves nothing.
• If the domain serves a site somewhere else today, create the TXT record first and switch the CNAME when you’re ready to move. The domain can’t become active until the CNAME points at Benchy.

What each state means

Only the first website to prove a domain gets it. Other websites waiting on the same name are dropped, and adding a domain that is already proven elsewhere says “That domain is connected to another website, or is still being removed.” Unproven domains are dropped after 7 days.

Keep the TXT record

If the record goes missing, the domain’s row warns you with the date it will stop serving. After 3 days without it, the domain stops serving. Put the record back and it serves again within about 6 hours.

What the domain serves

• The website’s live version, never a preview. Unpublishing or a suspension applies to the domain as well.
• The website keeps its benchy.site address. Add a <link rel="canonical"> to your pages to tell search engines which address is the main one.
• Benchy issues and renews the certificate. Browsers are told to use HTTPS for a week at a time, and nothing is set for your other subdomains.

Plans and caps

The cap is per workspace, across all its websites, and counts every domain except those being removed. When the plan changes to one with fewer domains, the oldest keep serving up to the new cap and the rest show Not serving. Nothing is deleted: they serve again when the plan allows. While the workspace is on hold after a suspension, none of its domains 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 this website within a few minutes; you can delete its DNS records afterwards. Once it is removed, anyone who proves it can add it again, with a new TXT value.