Skip to main content
This guide shows you how to use any domain name you already own, such as app.your-domain.com, with ngrok.
ngrok is not a domain registrar; you must already own a domain name to use it with ngrok.
Custom domains are only available on the Pay-as-you-go plan.

​
1. Add your domain in ngrok

On your dashboard’s Domain page, click the New Domain button to add your domain to your ngrok account. After it’s been added, you’ll be given a CNAME value such as exampledata.otherdata.ngrok-cname.com. Copy this for the next step.
You can also add a domain via the ngrok API. The CNAME will be in the "cname_target" field of the response object.

​
2. Configure DNS for your domain

For a subdomain such as app.example.com, navigate to your DNS provider’s dashboard and create a CNAME record in the example.com zone. (Check your provider’s support content if you’re unsure how to do this.) When configuring the record, use the following values:
  • type: CNAME
  • name: app (or app.example.com if your provider requires the full hostname)
  • value: the CNAME target you copied from ngrok
For an apex domain such as example.com, follow the apex domain instructions to configure an ALIAS, ANAME, or flattened CNAME record instead. A standard CNAME record cannot be used at a DNS zone apex.
Using a tool like dig or nslookup, you can test your DNS records in the terminal. For subdomains, check the CNAME record; for apex domains, check the A and AAAA responses, since aliasing or flattening returns IP addresses instead of a CNAME record.

​
3. Start an endpoint using your domain

To start an Agent Endpoint at your domain, run the following command in your terminal, replacing your-domain-here.example.com with the domain you added in the ngrok dashboard:

​
4. Wait for the TLS certificate to provision

After you add a custom domain, ngrok provisions a TLS certificate for it from an ACME provider such as Let’s Encrypt. This typically completes within a few minutes once your DNS records are resolvable, but can take longer depending on DNS propagation and the certificate authority. While the certificate is still provisioning, ngrok terminates HTTPS connections to your domain using a default ngrok wildcard certificate that does not match your custom hostname. If you start an endpoint and open the custom domain in a browser before the certificate is ready, you’ll see a certificate warning indicating that the hostname doesn’t match the certificate. This is expected during the provisioning window and resolves on its own as soon as the certificate is issued. There’s no action to take other than waiting and reloading.
You can see whether your certificate is still provisioning, ready, or blocked on a DNS error in two places:
  • Dashboard: open the Domains page and select your domain. The certificate status panel shows the current provisioning state and any error.
  • API: call GET /reserved_domains/{id} and read certificate_management_status.provisioning_job. The status field tells you whether provisioning is in progress, valid, or has hit a recoverable or user-correctable error, and retries_at tells you when ngrok will try again.
If provisioning_job reports a DNS error, double-check that the DNS records from step 2 are published and resolvable with dig or nslookup. For wildcard custom domains, both CNAME records described in TLS certificate provisioning must exist before the certificate can be issued.

​
Wildcard domains

If you bring your own wildcard domain (such as *.example.com), you must create a second CNAME record with your domain host for wildcard TLS Certificate provisioning.

​
Apex domains

An apex domain is the root of a DNS zone, such as example.com; app.example.com is a subdomain. ngrok supports apex domains with DNS providers that offer ALIAS, ANAME, or CNAME flattening. Check that your provider supports pointing these records to external hostnames. Add your apex domain in ngrok as described in step 1. In your DNS provider, create an ALIAS, ANAME, or flattened CNAME record at the apex, using @ or your provider’s equivalent for the name. Point the record to the CNAME target ngrok supplies for your domain. Your DNS provider resolves this target and returns A or AAAA records. Once DNS is configured correctly, ngrok automatically provisions a TLS certificate as described in step 4. If your DNS provider doesn’t support aliasing or flattening to ngrok’s target, use a subdomain such as app.example.com with a standard CNAME record, or move your domain’s DNS hosting to a compatible provider. You can keep your domain registered with your existing registrar.

​
Using custom domains with TCP endpoints

Public TCP endpoints are assigned randomly on an ngrok-controlled hostname with a randomly assigned port. You cannot choose the hostname or select the port. However, you can simulate a customized hostname by creating a CNAME record to the hostname of your assigned TCP address. If you do so, be aware that all ports on that hostname—even those provisioned to other accounts—will then be available on your domain. For example, if your TCP address is 5.tcp.ngrok.io:12345, you could create the following CNAME record:
Then you can access that TCP endpoint with: