Connect a custom domain
Point the domains you own at your published site, and understand why a domain sits on Pending instead of failing.
On this page
A custom domain puts your site on an address you own. A site can have up to 10 custom domains, and every one you connect serves the same site. Your free .modulify.website address keeps working alongside them, so nothing breaks while you set this up.
Before you begin
You need three things: a domain you already own, the ability to add DNS records for it, and a paid plan. On a free workspace the Custom Domain field is disabled, the row carries a Paid badge, and hovering Connect shows A paid plan is required to add a custom domain. See Plans.
Adding or removing a domain needs the Manage domains permission, which the workspace owner always has and which a custom role can be given. Without it the Connect button is disabled with the tooltip You do not have permission to do this. See Members and roles.
You can connect a domain before your first publish, but nothing answers on it until the site is published. The field says as much: Connect a custom branded domain. Every domain you add serves the same site and takes effect immediately if an initial publish exists.
Open the Domain panel
Open the project, click More in the tab strip, then Domain. The address is /dashboard/projects/<project>/domain, and the panel is headed Domain, Connect custom domains to your published site.
On a Free workspace you own, a published site also shows a Connect domain button in the strip above the preview frame. That one opens the plan and credits modal rather than this panel, because the field here stays disabled until the workspace is on a paid plan.
From top to bottom the panel holds your free subdomain, the Custom Domain field, then one card for each domain on the site in the order you added them, with your project's details underneath. The free subdomain is covered in Your free web address.
Enter the domain
Type the hostname into the Custom Domain field. The placeholder shows the two shapes it accepts, modulify.ai or blog.modulify.ai. Press Enter or click Connect. The field stays at the top of the panel however many domains the site has, so adding a second domain works exactly like the first.
Enter the bare hostname. The field validates as you type and refuses four things.
| Message | Cause |
|---|---|
| Domain should not include http:// or https://! | You pasted a full URL |
| Domain should not include a path! | The value contains a / |
| Domain must be between 4 and 253 characters! | Too short or too long to be a hostname |
| Domain must be a valid domain! | Not a well formed hostname |
Some endings are worth avoiding. Type a domain on an ending that many networks filter and a note appears under the field: Some networks and company firewalls refuse to resolve .lol domains, so a few visitors will see a server not found error. A .com or .org reaches more people. It is advice rather than an error, and Connect still works. Troubleshoot a domain explains what those networks actually block.
A leading www. is not an error. Modulify strips it and connects the root instead, then attaches the www hostname as the companion, so www.example.com and example.com reach the same place. See www and apex domains.
What happens on Connect
Modulify sets up the site's production server if it does not exist yet and works out the DNS record each hostname needs, for your domain and its www companion. The TLS certificates are issued once those records point at Modulify. Every domain you add is served by the same deployment, so a second domain changes nothing for the first.
You get a Domain added toast naming what is now waiting, for example example.com and www.example.com are both waiting on DNS. Add the required records at your DNS host to finish connecting them. A new card headed Your custom domain appears under the field, after the cards already there, with a table of records underneath, each row reading Pending until its record checks out. The field empties, ready for the next domain.
If the www hostname of the root you entered already belongs to this site or another one, Modulify adds the root on its own and the toast names only the root: example.com is waiting on DNS. Add the required records at your DNS host to finish connecting it.
When Connect refuses
| Message | Cause |
|---|---|
example.com is already connected to this site! |
The hostname is already on this site, as one of its domains or as the www variant of one |
example.com is already connected to another site! |
Another site holds that hostname |
A site can have up to 10 custom domains! |
The site already has 10 domains. Remove one first |
You cannot use a Modulify domain as a custom domain! |
The value is on an address Modulify already owns |
Once the site has 10 domains, the field and Connect are disabled, and hovering Connect shows A site can have up to 10 custom domains.
One site per domain
A hostname belongs to one site at a time across all of Modulify. To move a domain to a different site, remove it from the site that has it, then connect it on the other one. Deleting the site that has a domain frees it too, so another site can connect it.
Each domain has its own card
Every domain sits in a card of its own, headed Your custom domain, with the hostname and a Remove button. The description under the heading says where that domain stands.
| Description | When |
|---|---|
Links to your live site use this domain. |
The domain is connected and it is the primary |
Your site also answers on this domain. |
The domain is connected and another one is the primary |
Add the records below at your DNS host to connect this domain. |
The domain is not connected yet |
Not serving your site while paused. |
The site's custom domains are paused |
For a root domain, the card also holds its WWW variant row, see www and apex domains. When the domain's DNS provider supports one-click setup and a hostname on the card is not connected yet, the card starts with its own Connect with <your provider> button, which reads Connect automatically when the provider does not give its name, see One click setup.
The primary domain
One connected domain is the primary, and its card carries a Primary badge next to Connected. The primary is the domain under Your custom domain on the first card, in the order you added them, where that domain is connected. After a root was removed, that domain is its www hostname, and it still counts. Only while none of those domains is connected does the primary fall back to the first connected hostname in a card's WWW variant or Root domain row, and that row carries the badge instead.
Links to your live site use the primary. That covers Copy Published App Link and Open Published Project in the dashboard, the Custom Domain row of the publish popover, a template's preview link, the redirect hint on your free subdomain, and the customDomain that webhooks and AI clients read. Every other connected domain still serves the site in full.
The order cannot be changed. To make a later domain the primary, remove the cards added before it whose domain under Your custom domain is connected, root and www variant both, and connect them again, which puts them after it. When the primary is removed, the primary is worked out again from the domains that remain, by the same rule.
The records Modulify shows you
The table has four columns, Type, Name, Value and Status, and one row per record required for that hostname. When your domain's nameservers are Cloudflare, a fifth column, Proxy, reads Off on every row. Click a name or a value to copy it.
Above the table, a line names the zone the record belongs in: Add the following record at the DNS host that manages example.com (not any other domain). DNS changes can take a few minutes to propagate. That is whoever runs the nameservers for the domain today, which is often not the company you bought it from. Each domain can sit with a different DNS host, so read the line on each card.
Names are shown relative to your domain, so your apex reads @ rather than the full hostname.
DNS records explains what each record is for, the Cloudflare Proxy column, and the one click setup button that some DNS providers support.
Every record, then Connected
Modulify marks a hostname Connected when every record in its table resolves to Modulify and the certificate for it has been issued. For a root domain that is one A record. For the www hostname or a subdomain it is one CNAME.
Once the record points at Modulify, the certificate is usually issued within a minute or two and a Connected badge appears next to that card's heading on its own. Until then the heading carries no badge, so check each row's own Status: a row that stays on Pending or Invalid is the one to look at.
While you wait
The panel checks every domain when you open it, then keeps re-checking each domain that is not fully connected while you have it open, and the Connected badges appear without a refresh. Domains that are already connected are left alone. DNS usually propagates in minutes, though some providers take hours. How Modulify re-checks has the timings.
Your free .modulify.website address and your connected domains serve the whole time, so the site is never offline while a new domain is pending.
If a row reads Invalid, a banner under it names the exact problem. Troubleshoot a domain works through every cause in order.
A domain waiting on verification
An AI client can also add a domain by proving ownership first, with a TXT record, see start_domain_verification. While one is waiting, the panel shows Pending verification for example.com under the field, with the TXT record to add, a Verify & Connect button and Cancel. Verify & Connect adds the domain as a new card once the TXT record checks out, and the Domain verified toast says whether it is connected yet, for example example.com is verified and waiting on DNS. Add the required records at your DNS host to finish connecting it. A site has one pending verification at a time, and it does not stop you connecting other domains in the meantime.
On a free workspace Verify & Connect is disabled, and hovering it shows A paid plan is required to add a custom domain. Once the site has 10 domains it is disabled too, with A site can have up to 10 custom domains. Cancel still works.
Connecting the waiting domain through the field instead, or adding it on a card with Add www or Add root, clears the pending verification, because the domain is then on the site. If the domain is already on the site when you click Verify & Connect, it is refused with example.com is already connected to this site! and the pending verification is cleared too.
Replacing or removing a domain
Domains sit side by side, so moving to a new domain needs no gap. Connect the new one, wait for it to read Connected, then remove the old one. If the old one was the primary, the primary is worked out again from the domains that remain. When it has a connected www variant, though, removing it leaves that www hostname on the card as its own domain, still connected, so it stays the primary. Remove that hostname too when the new domain should become the primary.
Remove on a card asks first. The dialog is titled Remove example.com? and the confirm button reads Remove domain. The description depends on what else is there.
| Description | When |
|---|---|
Your site will stop working at example.com. www.example.com stays connected, remove it separately if you want that one gone too. |
The domain has a connected www variant |
Your site will stop working at example.com. www.example.com stays on the site, remove it separately if you want that one gone too. |
The domain has a www variant that is not connected yet |
Your site will stop working at example.com. Your other domains keep working. |
The site has other domains |
Your site will stop working at this domain. Anyone visiting it will see an error until you connect a new domain. |
It is the site's only domain |
The Domain removed toast then reads Your site is no longer reachable at example.com. Your other domains keep working., or ends with Connect another domain whenever you are ready. when it was the last one. Removing a domain never touches the other domains. When the domain has a www variant, the toast reads example.com was removed. www.example.com is still connected, remove it separately if you want that one gone too., or says the variant stays on the site when it is not connected yet, and its card stays with the www hostname in its place, see Removing one of them.
When your plan ends
A custom domain needs a paid plan to serve your site, not only to be added. When the workspace's plan ends and the workspace is on Free, the site's custom domains are paused. A payment that failed and is still being retried pauses nothing, and neither does a cancellation that is only scheduled, so the domains keep serving until the day the plan actually ends. A site moved into a workspace on Free has its custom domains paused the same way.
While they are paused:
- Every domain stays on its card, but none of them shows the site, and a visitor gets an error instead. Your free
.modulify.websiteaddress keeps working. - The panel shows Custom domains are paused above the cards,
They stay offline until this workspace is on a paid plan again., with a See plans button. - The cards lose their Connected and Primary badges and their records, and every domain on them reads
Not serving your site while paused. - Links to your live site use your free address instead, and the Custom Domain row of the publish popover offers Add a custom domain.
- Remove still works. Adding a domain again later needs a paid plan.
Nothing is deleted, and no DNS record has to change. Once the workspace is on a paid plan again, the domains come back on their own, usually within a minute or two.
From chat
You can also ask chat to connect a domain, in plain words such as connect example.com to my site. It adds the domain and its www variant, then reads you the exact records to add at your DNS provider, or gives you a one-click setup link when your provider supports it. Once you have added them, ask it to check again. It runs the same checks as the Connect button: a paid plan and the Manage domains permission. Chat can remove a domain or its www variant too, after you confirm. Adding the records at your DNS provider is always yours to do.
From an AI client over MCP
A connected AI client manages the same domains with the custom domain tools. get_domain_status and get_domain_connect_url need the config:read scope, and the tools that add or remove a domain need config:write. Every domain carries an _id, returned by get_domain_status and add_custom_domain, and the tools that act on one domain take it as domainId. While the domains are paused, get_domain_status answers with paused set to true and lists them as they are, without checking their DNS. See Tokens and scopes.
Next
- DNS records lists the records and what each one does.
- Troubleshoot a domain covers a domain stuck on Pending.
- www and apex domains covers the second hostname of each domain and picking one canonical address.
- Publish a site is what a connected domain needs before it serves anything.