> For the complete documentation index, see [llms.txt](https://docs.countercyclical.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.countercyclical.io/workspace-settings/custom-subdomains.md).

# Custom Subdomains

Connect a branded hostname to your workspace and route public shared resources through your own domain.

Custom Subdomains let you serve supported Countercyclical resources from a hostname you control rather than the default Countercyclical domain. This is useful when externally shared research, reports, or other public resources should appear under your organization’s domain.

See also [Whitelabeling](https://docs.countercyclical.io/workspace-settings/whitelabeling) and [Network Access](https://docs.countercyclical.io/workspace-settings/network-access).

You can configure custom subdomains from [**Settings › Workspace › Advanced › Access**](https://dashboard.countercyclical.io/settings/workspace/advanced/access).

### Add a Custom Subdomain

Enable **Custom Subdomains**, then enter the hostname you want to connect and select **Add Hostname**. Use a subdomain such as `research.example.com` rather than your root domain.

After adding the hostname, Countercyclical provides the DNS record required to route it. The configuration shown uses a **CNAME** record pointing your hostname to the Countercyclical-provided target.

Add that record through your DNS provider exactly as displayed in the workspace.

### Verify the Hostname

New hostnames remain in a **Pending DNS** state until the required DNS record can be resolved and provisioning completes.

Once you have added the DNS record:

1. Allow time for the DNS change to propagate.
2. Return to [**Advanced › Access › Custom Subdomains**](https://dashboard.countercyclical.io/settings/workspace/advanced/access).
3. Select **Verify** next to the hostname.
4. Wait for verification and provisioning to complete.

You can use the adjacent external-link control to open the hostname once it is available.

{% hint style="info" %}
**Note:** DNS changes are not always visible immediately. If verification fails shortly after adding the record, confirm that the CNAME matches the value shown in Countercyclical and retry after propagation.
{% endhint %}

### Provisioning Status

Countercyclical displays the current state directly beneath each hostname. A hostname may remain pending while DNS validation or downstream provisioning is incomplete.

If you see **Provisioning needs attention**, review the accompanying error before retrying verification. For example, a provisioning provider may reject the hostname even when the hostname has already been added to your workspace.

Do not direct production traffic to the custom hostname until its configuration has been successfully verified.

### Managing Custom Subdomains

Existing hostnames can be reverified or removed from the same **Custom Subdomains** section. If you change DNS providers or modify the underlying DNS record, recheck the hostname's status to ensure the required CNAME remains intact.

Disabling **Custom Subdomains** stops the workspace from using the feature, but you should also review any DNS records maintained with your DNS provider when decommissioning a hostname.

#### Related Pages

{% content-ref url="/pages/Vm5FUezpCUGGOP2muJKa" %}
[Network Access](https://docs.countercyclical.io/workspace-settings/network-access.md)
{% endcontent-ref %}

{% content-ref url="/pages/zR92M6x8tWA3Qi8I2ADU" %}
[Whitelabeling](https://docs.countercyclical.io/workspace-settings/whitelabeling.md)
{% endcontent-ref %}

{% content-ref url="/pages/m1LiKKzPdEyTgZGZ89be" %}
[Verified Domains](https://docs.countercyclical.io/workspace-settings/verified-domains.md)
{% endcontent-ref %}
