Custom Domains

Updated October 29, 2026

When you create a reverse proxy service, you need to assign it a domain. NetBird provides built-in domains that are automatically available for every account, and also supports custom domains where you bring your own domain name. This page explains how both types work and walks you through adding and verifying a custom domain.

Built-in domains

NetBird Cloud provides built-in domains without additional DNS configuration. Self-hosted cluster domains become usable once the operator has configured the proxy and its DNS records. The format and labeling of these domains differ between cloud and self-hosted deployments.

Cloud deployments (Free domains)

Cloud accounts receive free domains in the format:

{subdomain}.{nonce}.{cluster}.proxy.netbird.io

For example: myapp.abc123.eu.proxy.netbird.io where myapp is your chosen subdomain, abc123 is a nonce unique to your account, and eu is the proxy cluster region.

NetBird operates multiple proxy clusters in different regions, and your available free domains correspond to these clusters. In the domain selector, free domains appear with a Free badge.

Self-hosted deployments (Cluster domains)

Self-hosted deployments provide cluster domains in the format:

{subdomain}.{proxy-domain}

For example: myapp.proxy.mycompany.com where myapp is your chosen subdomain and proxy.mycompany.com is the domain configured on your proxy instance(s) via the NB_PROXY_DOMAIN environment variable.

There is no nonce in self-hosted domains. In the domain selector, shared clusters have a Shared badge and account-specific clusters have an Account badge.

How built-in domains are derived

In both deployment types, built-in domains are dynamically derived from the proxy instances currently connected to the management server. They are not pre-provisioned - they reflect whichever proxy servers are actively registered via gRPC. If a proxy instance disconnects, its associated domain may no longer appear in the selector until the instance reconnects.

Built-in domains are a quick way to get started. They receive automatic TLS certificates and work the same as custom domains in every other respect.

Custom domains

Custom domains let you use your own domain name (e.g., app.example.com) for reverse proxy services. Custom domains work identically in both cloud and self-hosted deployments. Before a custom domain can be used, you must verify ownership by creating a CNAME record in your DNS provider.

To manage custom domains, navigate to Reverse Proxy > Custom Domains in the NetBird dashboard.

Adding a custom domain

Follow these steps to add a custom domain to your account:

1. Navigate to Reverse Proxy > Custom Domains in the NetBird dashboard.
2. Click Add Domain.
3. Enter your domain name (e.g., proxy.example.com).
4. Select the target proxy cluster that will handle traffic for this domain.
5. Click Save.

NetBird stores new domain names in lowercase and converts internationalized names to ASCII (punycode). A trailing dot is removed. Equivalent spellings, such as App.Example.com. and app.example.com, refer to the same registration. Invalid names and wildcard registrations such as *.example.com are rejected; enter the domain without the wildcard prefix.

After saving, the domain appears in your list with a Pending Verification status. You must complete CNAME verification before you can use the domain with a service.

Verifying a custom domain

To prove that you own the domain, NetBird requires you to create a specific CNAME record in your DNS provider.

Step 1: Create the CNAME record

In your DNS provider, create a wildcard CNAME record for your custom domain, pointing to the proxy cluster address. The CNAME target depends on your deployment type:

• Cloud deployments - point to a NetBird-hosted cluster address (e.g., eu.proxy.netbird.io)
• Self-hosted deployments - point to your own proxy hostname (e.g., proxy.mycompany.com, without a URL scheme or port)

For example, on a cloud deployment:

On a self-hosted deployment:

The exact target value depends on the proxy cluster you selected when adding the domain. The NetBird dashboard displays the required CNAME record and target after you save the domain.

Check your CAA records

A CAA record lists the certificate authorities allowed to issue certificates for a domain. If your domain has CAA records and none of them authorize the certificate authority the proxy uses, certificate issuance is refused and your services are unreachable over HTTPS.

If no applicable CAA records restrict issuance, no CAA changes are needed.

Which certificate authority to authorize

NetBird Cloud issues certificates through ZeroSSL on all shared proxy clusters, and ZeroSSL certificates are signed by Sectigo. The value to authorize is therefore sectigo.com.

Add the records

If the applicable CAA policy excludes your proxy's certificate authority, authorize it with an issue record. For example, if the applicable records are at proxy.example.com:

Some DNS providers ask for flags, tag, and value in separate fields, as above. Others accept the full zone file line:

proxy.example.com. 3600 IN CAA 0 issue "sectigo.com"

The issue tag also covers wildcard certificates unless an issuewild policy overrides it. Add issuewild only when you need a separate wildcard policy. A wildcard DNS record does not require a wildcard certificate. Preserve any other certificate authorities your services need in the applicable record set.

Verify the records

Start with an actual service hostname, then inspect its CNAME target and parent names as needed:

dig CNAME dashboard.proxy.example.com +short
dig CAA dashboard.proxy.example.com +short
dig CAA proxy.example.com +short
dig CAA example.com +short

Empty output from the parent queries alone does not rule out CAA restrictions at a CNAME target. Check the applicable record set for the certificate authority your proxy uses.

Step 2: Verify in the dashboard

After creating the DNS record, return to the Reverse Proxy > Custom Domains page and click Verify Domain next to the domain.

Confirm that the dialog reflects the CNAME record you added to your DNS provider and click Start Verification.

NetBird performs a CNAME lookup on validation.<your-domain> and checks that the resulting hostname matches the proxy cluster selected for the registration. The wildcard CNAME normally answers this lookup. Once verification succeeds, the domain status changes to Active and it becomes available in the domain selector when creating or editing services.

Verification deadline

Complete verification within 48 hours of adding a custom domain. Retrying verification does not extend this deadline. Once a domain becomes Active, it is exempt from this expiry.

NetBird removes expired, unverified registrations at management server startup and every 60 minutes. With management running normally, removal happens between 48 and 49 hours after registration. The account's activity log records Unvalidated domain registration expired. After removal, you can add the domain again and complete verification within a new 48-hour window.

Managing custom domains

The Custom Domains page lists only custom domains. Built-in domains from cloud and self-hosted proxy clusters are available in the service domain selector but are excluded from this table.

Viewing domains

The table has Domain, Status, and Cluster columns showing the custom domain name, its verification status, and the associated proxy cluster, plus actions to verify or delete the domain.

Retrying verification

While a custom domain is Pending Verification, fix any DNS issues and click Verify Domain to retry within its 48-hour window. Once a domain is Active, DNS changes do not automatically reset its verification status. An active status records successful verification; it does not guarantee that the current DNS configuration still routes traffic correctly.

Deleting a custom domain

To remove a custom domain, click the delete action next to the domain in the list. Deleting a custom domain removes it from your account and makes it unavailable for any new services. Built-in domains cannot be deleted.

Using domains with services

When you create or edit a reverse proxy service, the domain selector presents all available domains:

• All Active custom domains
• All built-in domains from the available proxy clusters

To assign a domain to a service, enter a subdomain on the left side of the selector and choose a base domain on the right side. The full public URL for your service is the combination of both:

{subdomain}.{base-domain}

For example, if you enter dashboard as the subdomain and select proxy.example.com as the base domain, the service is accessible at dashboard.proxy.example.com.

All domain types receive automatic TLS certificates managed by the proxy.

Troubleshooting

Domain shows as Pending Verification

Verify that the wildcard CNAME record for *.<your-domain> points to the selected proxy cluster hostname. Query the same hostname NetBird uses for verification:

dig CNAME validation.proxy.example.com +short

The result should match the target shown in the dashboard, such as eu.proxy.netbird.io or proxy.mycompany.com. If it is missing or different, check for typos, DNS propagation delays, and an explicit record at validation.proxy.example.com that overrides the wildcard.

CNAME pointing to the wrong cluster

The CNAME lookup must return the cluster selected when the domain was added. Pointing to another available cluster still fails verification. Check the expected target on the Custom Domains page and update your DNS record accordingly.

Certificate is not issued after verification

An Active domain has passed the CNAME check, but certificate issuance can still fail. Check the service's certificate status and, on self-hosted proxies, the proxy logs. If the error identifies CAA, follow Check your CAA records for the service hostname and authorize the proxy's certificate authority in the applicable record set. Also check DNS resolution and the proxy's TLS challenge requirements.

Domain already in use

Each custom domain must be unique across all NetBird accounts. If you receive an error that the domain is already in use, it may be registered by another account. Verify that you are entering the correct domain name. If you believe this is an error, contact NetBird support.

Related pages

• Reverse Proxy Overview - learn how the reverse proxy feature works
• Authentication - configure SSO, password, PIN, and header authentication, plus access restrictions
• Access Logs - monitor traffic to your reverse proxy services