# Use a custom domain

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.

```text
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

1. In the portal, go to [**Settings**](https://auth.faustine.ai/go?to=%2Fsettings%3Ftab%3Ddomain) and select **Custom domain**.
2. Under **Add your domain**, enter the hostname, without `https://` or a path.
3. 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):

1. Under **Use this domain in my URLs**, select **Use this domain**.
2. 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.

1. Under **Remove this domain**, select **Remove domain**.
2. In the dialog, select **Remove domain**.
3. 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](https://docs.faustine.ai/agent-gateway/connect-clients/): add a client with the new address.
- [Set the look and feel of your gateway](https://docs.faustine.ai/agent-gateway/look-and-feel/): put your name and logo on the sign-in page served from your domain.
- [Environments](https://docs.faustine.ai/agent-gateway/environments/): the path segment each environment adds to the address.