> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a custom domain

> Point your own domain at a deployed Brimble project.

Point your own domain at a deployed Brimble project. Brimble issues a TLS certificate via Let's Encrypt automatically.

## Prerequisites

* A project already running at `<project-name>.brimble.app`. If you haven't deployed yet, follow the [quickstart](/getting-started/quickstart) first.
* A domain you control, with access to its DNS settings.

## Step 1: Add the domain in Brimble

1. Open your project in the [dashboard](https://app.brimble.io).
2. Go to the **Domains** tab.
3. Click **Add domain** and enter the hostname you want to use (e.g. `app.example.com`).

Brimble shows you the DNS record to set at your provider.

<Frame caption="The Add Domain dialog with the CNAME record to copy.">
  <img src="https://mintcdn.com/brimble-86/VDnKCHWcGHKvY1rj/images/domains/add-cname-record.jpg?fit=max&auto=format&n=VDnKCHWcGHKvY1rj&q=85&s=8856d1e8b86eca83ee41b0d638f0a01c" alt="Add Domain dialog showing the CNAME record Brimble expects" width="5088" height="3366" data-path="images/domains/add-cname-record.jpg" />
</Frame>

## Step 2: Set the DNS record

You have two options at your DNS provider, depending on whether you're pointing a subdomain or an apex domain.

### Option A, CNAME (recommended for subdomains)

Use this for any subdomain like `app.example.com`, `api.example.com`, or `www.example.com`.

| Type  | Name              | Value                 |
| ----- | ----------------- | --------------------- |
| CNAME | `app` (subdomain) | `gateway.brimble.app` |

### Option B, A record (for apex domains)

Most DNS providers don't allow CNAMEs at the root (`example.com`). For an apex, point an **A record** at Brimble's edge IP:

| Type | Name | Value            |
| ---- | ---- | ---------------- |
| A    | `@`  | `157.90.225.125` |

`@` is the standard placeholder for the apex; some providers use a blank name field or your domain itself instead, follow your provider's convention.

If your DNS provider supports CNAME flattening or ALIAS records (Cloudflare, Route 53, DNSimple, and others), an `ALIAS` or flattened `CNAME` to `gateway.brimble.app` works too and is preferable when available, it tracks edge IP changes automatically.

## Step 3: Wait for verification

Once DNS propagates, Brimble:

1. Verifies the record resolves to its edge.
2. Requests a TLS certificate from Let's Encrypt.
3. Marks the domain as **active** in the dashboard.

Propagation usually takes a few minutes but can take up to 24 hours, depending on your DNS provider's TTL.

<Warning>
  **A `CAA` record can block Let's Encrypt.** If TLS issuance gets stuck and you have a `CAA` record at the apex, it must list `letsencrypt.org`, otherwise the cert never issues. Check with `dig your-domain.com CAA +short` and add `letsencrypt.org` or remove the record entirely.
</Warning>

## Troubleshooting

**Domain stuck on "verifying."** DNS hasn't propagated yet. Check from a third party:

```bash theme={null}
dig your-domain.com +short
```

The output should match the value Brimble showed you. If it doesn't, double-check the record at your DNS provider, typos in the target hostname are the most common cause.

**TLS certificate fails to issue.** Let's Encrypt requires the domain to resolve to Brimble's edge before issuing a certificate. If DNS is correct, Brimble retries automatically; wait a few minutes. If it still fails after an hour, check that no `CAA` record on your domain blocks Let's Encrypt:

```bash theme={null}
dig your-domain.com CAA +short
```

If a `CAA` record exists and doesn't list `letsencrypt.org`, add `letsencrypt.org` or remove the record.

**Mixed-content warnings in the browser.** Your app is loading some assets over HTTP on an HTTPS page. Audit your code for hardcoded `http://` URLs.

## Removing a domain

In **Domains**, click the trash icon next to the domain. Brimble revokes the certificate and stops accepting traffic for that hostname. Remove or update the DNS record at your provider afterward so it doesn't dangle.

## Manage DNS in Brimble

If you'd rather manage DNS records inside the Brimble dashboard than at an external provider, change your domain's nameservers to:

* `ns1.brimble.io`
* `ns2.brimble.io`

Once those nameservers are active, you can manage all DNS records (A, CNAME, MX, TXT, SPF, NS) for the domain from the dashboard.

## Next steps

* Push a new deployment, your custom domain stays attached across deployments.
* Add a second domain to the same project for staging vs. production hostnames.