# Custom domains

> Connect your own domain or subdomain to a Hyperclay document, configure DNS records, and check live status and TLS certificates.

Source: https://hyperclay.com/docs/custom-domains/

You can point your own bare domain (such as `example.com`), subdomain (such as `app.example.com`), or wildcard domain (such as `*.example.com`) at any document in Hyperclay. You can also point a bare domain or subdomain at a folder that is a [multi-page site](https://hyperclay.com/docs/multi-page-sites/). Hyperclay serves the document or folder at that address and provisions and renews TLS certificates automatically.

Custom domains are included on the [Personal and Maker plans](https://hyperclay.com/docs/billing/), with no limit on the number of custom domains you can connect. On a [team](https://hyperclay.com/docs/teams/), only the team owner can add or remove custom domains.

## Add a custom domain

1. Open the document's menu and choose **Custom domains** (or switch to the document's **Domains** tab). For a site folder, open the folder's menu and choose **Custom domains**.
2. Under **Custom domains**, click **Add domain**.
3. In the **Domain** field, enter a bare domain like `example.com`, a subdomain like `app.example.com`, or a wildcard like `*.example.com` (required if the document accepts [sign-ups](https://hyperclay.com/docs/sign-up-apps/)). Enter the hostname only, without `https://`, a port, a path, or a query string.
4. When you enter a bare domain, **Also send `www.<domain>` here** appears below the field. Keep it checked so requests to `www.<domain>` redirect to your bare domain.
5. Click **Add domain**.

> [!TIP]
> Keep **Also send `www.<domain>` here** checked when connecting a bare domain. Browsers treat `example.com` and `www.example.com` as two separate origins, so a visitor who switches between them loses browser-stored drafts, saved data, edit mode, and share links, and search engines index two copies of the document.

Hyperclay refuses hostnames that are not registrable public domains (`Use a registrable public domain.`), domains already connected to one of your documents (`This domain is already added to one of your sites.`), or domains that conflict with an existing mapping on another account (`This domain conflicts with an existing domain mapping.`).

## Point a domain at a site folder

A domain on a [site](https://hyperclay.com/docs/multi-page-sites/) folder serves the whole folder:

- `index.html` at `/`
- the other pages at their [clean addresses](https://hyperclay.com/docs/multi-page-sites/#clean-addresses), such as `/about` for `about.html`
- uploads at their paths inside the folder
- 404 for a path that names nothing

Only a folder that is a site can have a domain. A folder is a site when it holds a `site.json` file. Wildcard domains cannot point at a folder. If you rename or move the folder, its domain keeps working.

A Hyperclay subdomain can point at a site folder too: choose **Hyperclay subdomain** in the folder's menu.

## DNS records on the Domains page

After you add a domain, the **DNS setup** section on the **Domains** page lists the exact DNS records to create at your registrar or DNS host. The table has four columns: **Purpose**, **Type**, **Name**, and **Value**.

| Purpose | Type | Name | Value |
|---|---|---|---|
| **Traffic** (bare domain) | `A` | Your bare domain (`example.com` or `@`) | `5.161.29.91` |
| **Traffic** (subdomain or wildcard) | `CNAME` | Your subdomain (`app.example.com` or `*.example.com`) | `domains.hyperclay.com` |
| **Validation** | `CNAME` | `_acme-challenge.<domain>` | The token target shown in your **DNS setup** table |

If you checked **Also send `www.<domain>` here**, the table also lists the records for `www.<domain>`.

> [!WARNING]
> Keep the `_acme-challenge` **Validation** `CNAME` record in place permanently (`Keep this validation record in place so certificates can renew.`). If you use Cloudflare, set both the traffic and validation records to DNS only (grey cloud) so Hyperclay can validate your domain and terminate TLS directly.

A new domain claim stays open for 7 days while waiting for DNS records to point to Hyperclay. If the 7-day window expires before you configure DNS, re-adding the same domain reopens the claim window with the same DNS records.

## Check whether a domain is live

The **Custom domains** table lists each connected domain with three status columns:

- **Domain**: The hostname, the date it was added, and `Redirects to <domain>` on companion `www` entries.
- **Status**: **Pending** while waiting for DNS, **Active** once traffic routing is verified, or **Failed**.
- **TLS**: **Pending** while the certificate is being requested, **Issued** once HTTPS is live, or **Failed**.

Opening the **Domains** page or clicking **Refresh status** queues a background DNS and certificate check (checks run at most once a minute). When **Status** shows **Active** and **TLS** shows **Issued**, your domain is live over HTTPS.

If a domain shows **Failed**, the row explains why: the DNS proof was removed after activation, the 7-day claim window expired before DNS pointed to Hyperclay, the domain conflicted with another reservation, or the certificate could not be renewed. Fix the DNS records shown in **DNS setup** and click **Refresh status**.

## Remove a custom domain

You can remove a custom domain at any time, even if your subscription has ended.

1. Open the document's **Domains** panel, or choose **Custom domains** in the site folder's menu.
2. Click **Remove** beside the domain you want to disconnect.
3. In the **Remove `<domain>`?** dialog, type the exact domain name into **Domain to remove** to confirm.
4. Click **Remove domain**.

Links using that domain stop opening the document or site immediately. The document or folder itself is not deleted and stays reachable at its Hyperclay address.

If a document has [sign-ups](https://hyperclay.com/docs/sign-up-apps/) enabled, its wildcard domain cannot be removed until you turn sign-ups off (`Wildcard domains cannot be removed while signups are enabled.`).
