Use a custom domain | Faustine Docs

A custom domain serves every gateway of your workspace from a hostname you own: MCP, REST, the API reference, the OpenAPI document, SKILL.md and the sign-in page. It belongs to the workspace, so one hostname serves every gateway, each under its slug. The Faustine address keeps working next to it.

https://gateway.faustine.ai/<workspace>/<gateway>/mcp     The Faustine address
https://gateway.example.com/<gateway>/mcp                 Your domain replaces the host and the workspace
https://gateway.example.com/<gateway>/staging/mcp         An environment stays a path segment

Before you begin

A domain whose DNS records you can edit.
A subdomain to use, such as gateway.example.com. Any subdomain works. Root domains (example.com) and wildcards are not supported.
If the domain has a CAA record, it has to allow letsencrypt.org.

Add your domain

In the portal, go to Settings and select Custom domain.
Under Add your domain, enter the hostname, without https:// or a path.
Select Add domain.

The page now shows four steps and the two DNS records to create.

Create the DNS records

Create both records at your DNS provider. The page shows the exact name and value of each, with a button to copy them.

Type	Name	Value	Purpose
`TXT`	`_faustine-challenge.gateway.example.com`	`faustine-verify=…`	Proves the domain is yours. It does not change where the hostname points.
`CNAME`	`gateway.example.com`	`custom.faustine.ai`	Sends the traffic of the hostname to Faustine.

If your provider adds the domain to the name for you, enter only the part before it: _faustine-challenge.gateway and gateway.

Note

If your provider offers a proxy or CDN switch for the CNAME record, such as the orange cloud in Cloudflare, leave it off (DNS only). A proxied record hides where the hostname points, and the certificate cannot be issued.

Wait for the checks

Faustine checks the records on its own and marks each step as it passes. To check immediately, select Check now.

Step	Passes when
Prove the domain is yours	The TXT record is visible with the value shown.
Point the hostname to Faustine	The CNAME record is visible.
Certificate	The certificate has been issued. Faustine requests it from `letsencrypt.org` once the hostname points to Faustine, and renews it.
Ready	Every gateway of the workspace answers on your domain, next to its Faustine address.

A DNS change takes from a minute to a few hours to be visible. If the records have not appeared after 7 days, Faustine stops checking until you select Check again.

Show your domain in the portal

When the domain is Ready, the portal still shows the Faustine address. To make the portal show your domain wherever a gateway URL appears (the Connect tab, the snippets, the CLI page and the API reference):

Under Use this domain in my URLs, select Use this domain.
In the dialog, select Use this domain.

To go back, select Switch back to the Faustine address. Both addresses keep working in either case.

Move clients that are already connected

Nothing changes for a connected client until you move it. To an MCP client a new address is a new server, and each address signs people in separately.

A client that signs in with a gateway user (Claude, ChatGPT, Cursor, VS Code, the CLI): add the gateway again with the new URL and sign in once. The old entry keeps working on the Faustine address until you remove it.
A client that uses an API key: change the URL. The key works on both addresses.

A session opened through one address is not valid on the other.

Remove the domain

Warning

Removing a domain that is being served stops it immediately. Everyone who signed in through it is signed out, and clients connected to it stop working until you add them again with the Faustine address.

Under Remove this domain, select Remove domain.
In the dialog, select Remove domain.
Delete the two records at your DNS provider.

The hostname stays reserved for your workspace for 30 days.

Troubleshooting

Symptom	Cause	Fix
The domain shows Waiting for the TXT record	The TXT record is not visible yet.	Wait for the DNS change to spread, then select Check now.
The domain shows TXT record mismatch	A verification record exists with a different value.	Replace its value with the one on the page.
The domain shows Waiting for DNS	The hostname does not point to `custom.faustine.ai`.	Create the CNAME record, DNS only, not proxied.
The domain shows Certificate blocked	A `CAA` record does not allow `letsencrypt.org`, or the CNAME record is proxied.	Add `0 issue "letsencrypt.org"` to the `CAA` record, turn the proxy off, then select Check now.
The domain shows Needs attention	The hostname stopped pointing to Faustine. The domain is still served for 7 days, and the page shows the deadline.	Fix the CNAME record. The domain goes back to Ready on its own.
The domain shows Stopped	The records did not appear within 7 days, or the hostname stopped pointing to Faustine more than 7 days ago.	Fix the records and select Check again.

Next steps

Connect clients: add a client with the new address.
Set the look and feel of your gateway: put your name and logo on the sign-in page served from your domain.
Environments: the path segment each environment adds to the address.