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

# Custom domains

> Deliver Convertly Image CDN assets from a branded hostname with automatic DNS verification and managed SSL.

Custom domains replace `cdn.convertly.sh` with a hostname you control:

```text theme={"system"}
https://images.example.com/{fileIdOrSlug}?w=1200&format=auto
```

The custom hostname maps to one CDN endpoint in your Convertly workspace. The endpoint namespace is omitted from custom-domain URLs, while the equivalent `cdn.convertly.sh` URL keeps it:

```text theme={"system"}
https://cdn.convertly.sh/production/{fileIdOrSlug}?w=1200&format=auto
https://images.example.com/{fileIdOrSlug}?w=1200&format=auto
```

Both URLs remain valid. Moving files between folders does not change either URL because delivery uses the file UUID or CDN slug.

Custom domains are available on Starter and higher plans. See [Limits](/limits#image-cdn) for the number included with each plan.

## Before you start

* Use a dedicated hostname such as `images.example.com`, `cdn.example.com`, or `media.example.com`.
* Do not reuse a hostname that already serves your website or application.
* You must be a workspace owner or admin to add, change, or remove a domain.
* Confirm the dashboard's current default CDN endpoint is the one the hostname should represent. A newly added hostname attaches to that endpoint.

## Add a domain

Open **Images > Domains** in the dashboard, or go directly to:

```text theme={"system"}
https://convertly.sh/app/image-cdn?tab=domains
```

Select **Add domain** and enter the complete hostname without a protocol or path.

Convertly attaches the hostname to the workspace's current default CDN endpoint. If it should serve a different endpoint, set that endpoint as the default before adding the hostname. One hostname maps to one endpoint.

Convertly immediately registers the hostname with its managed CDN provider and generates two DNS records:

| Type    | Name                                           | Value                                     | Purpose                                     |
| ------- | ---------------------------------------------- | ----------------------------------------- | ------------------------------------------- |
| `CNAME` | Your complete hostname                         | `cdn.convertly.sh`                        | Routes the hostname to Convertly's CDN edge |
| `TXT`   | `_convertly-verify.` followed by your hostname | A unique `convertly-domain-verify=` token | Proves control of the hostname              |

Use the exact names and values shown in the dashboard. Keep the CNAME in **DNS only** mode if your DNS provider offers an additional proxy option.

<Warning>
  Do not copy the example hostname or verification token from this page. Every domain receives a unique TXT value.
</Warning>

## Automatic Cloudflare setup

If the domain uses Cloudflare DNS, select **Set up with Cloudflare**. Convertly uses the Domain Connect synchronous authorization flow, which asks you to approve only the CNAME and TXT records shown on the authorization page.

The flow does not grant Convertly ongoing access to your Cloudflare account. After approval, the popup returns a completion signal to the existing Convertly page and Convertly checks the DNS records immediately. Normal background checks continue while DNS propagates.

If automatic setup is unavailable for the domain, add the two records manually. Manual and Domain Connect setup produce the same DNS configuration.

## Automatic verification

The Domains page checks incomplete domains when the page opens, every 15 seconds while it remains visible, immediately after Domain Connect completes, and again when you return to the browser tab. There is no manual refresh step.

The setup moves through these states:

| State       | Meaning                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------- |
| Checking    | Convertly is looking for the required CNAME and TXT records                                   |
| SSL pending | Ownership and routing are verified; the managed certificate is still being issued or deployed |
| Verified    | DNS, hostname activation, and the managed certificate are ready                               |
| Failed      | The CDN provider rejected or could not validate the hostname                                  |

Convertly treats the domain as ready only after the CNAME and TXT records are detected, the CDN hostname is active, and its SSL status is active. Hostname activation and certificate deployment are separate checks, so **SSL pending** can briefly remain after DNS is correct.

<Note>
  DNS may appear at different times from different resolvers. Keep the page open or return later; verification resumes automatically.
</Note>

## Use the domain

After verification, the domain card shows the production delivery pattern and a **Copy URL** action:

```text theme={"system"}
https://images.example.com/{slug}
```

Choose **Set as default** when new URLs copied for that CDN endpoint should use the custom hostname. Setting a default does not invalidate existing `cdn.convertly.sh` links or links from another verified hostname.

With the JavaScript Image CDN SDK:

```ts theme={"system"}
import { createConvertlyCdn } from "@convertly-sh/image";

const imageCdn = createConvertlyCdn({
  namespace: process.env.NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE!,
  baseUrl: "https://images.example.com",
});

const url = imageCdn.url("hero-summer", {
  width: 1200,
  format: "auto",
});
```

The namespace still identifies the endpoint in your SDK configuration, but it is not inserted into a custom-domain URL path.

## Public and signed endpoints

A custom domain keeps the access policy of its mapped CDN endpoint:

| Endpoint policy | Custom-domain behavior                        |
| --------------- | --------------------------------------------- |
| Public          | Anyone with the URL can request the asset     |
| Signed          | Requests require a valid signature and expiry |

Attaching a custom domain does not make a public endpoint private. Use a signed endpoint for customer-private media and generate signatures only from a trusted backend. See [Presets and signing](/docs/image-cdn/presets-and-signing).

## Changing or removing a domain

To move traffic to a new hostname:

1. Add and verify the new hostname.
2. Set it as the default for the CDN endpoint.
3. Update your application configuration.
4. Keep the old hostname connected for as long as previously published URLs must work.

When removing a domain, Convertly first removes the managed custom hostname from its CDN provider. The database record is removed only if provider cleanup succeeds, which avoids leaving an orphaned billable hostname. Remove the customer DNS records after the domain disappears from Convertly.

## Troubleshooting

| Symptom                                   | Check                                                                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| CNAME stays undetected                    | Confirm the complete hostname resolves directly to `cdn.convertly.sh` and any DNS proxy is disabled                            |
| TXT stays undetected                      | Confirm the record name begins with `_convertly-verify.` and the value includes the complete `convertly-domain-verify=` prefix |
| SSL pending                               | Leave the CNAME in place. Certificate issuance starts after routing is visible and may finish after ownership verification     |
| Domain returns an origin or routing error | Confirm the domain card is Verified and the CNAME still points to Convertly                                                    |
| Domain entered a failed state             | Check for restrictive CAA records, a conflicting hostname at another provider, or contact Convertly support                    |
| Domain Connect button is unavailable      | Add the displayed records manually; the DNS provider may not expose or onboard the Convertly Domain Connect template           |

You can inspect public DNS from a terminal:

```bash theme={"system"}
dig CNAME images.example.com
dig TXT _convertly-verify.images.example.com
```

For production traffic, wait for the dashboard to show **Verified** before switching application URLs.

## Related documentation

<Columns cols={2}>
  <Card title="Set up Image CDN" icon="images" href="/guides/image-cdn-setup">
    Create an endpoint, select its access policy, and deliver the first asset.
  </Card>

  <Card title="URL structure" icon="link" href="/docs/image-cdn/url-structure">
    Compare Convertly-hosted and custom-domain URL shapes.
  </Card>

  <Card title="Signed delivery" icon="key" href="/docs/image-cdn/presets-and-signing">
    Protect private delivery with expiring signatures.
  </Card>

  <Card title="Transforms" icon="crop" href="/docs/image-cdn/transforms">
    Review every supported delivery parameter.
  </Card>
</Columns>