Skip to main content

How Do I Use A Custom Domain?

This guide will show you the steps to use any domain name that you already own with ngrok, e.g. app.your-domain.com.

note

ngrok is not a domain registrar; you must already own a domain name to use it with ngrok.

1. Create a domain in ngrok​

You can create a domain in the ngrok dashboard. You can do so by going here.

When your domain is created, you'll be given a CNAME value such as exampledata.otherdata.ngrok-cname.com. Copy it.

info

You can also create a Domain via the ngrok API. The CNAME will be in the "cname_target" field of the response object.

2. Add the CNAME record to your domain​

  1. In a new browser tab, navigate to your domain hosting provider's dashboard and create a CNAME record. Check your hosting provider's support content or documentation to learn how.

    • Typically, this process includes creating a DNS record.

  2. When configuring the record, use the following values:

    • Its type should be CNAME
    • Its name should be @
    • Its value should be the CNAME value you copied from the ngrok dashboard or API response.
Test your CNAME record

Using a tool like dig or nslookup, you can test your CNAME record in the terminal.

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 created in the ngrok dashboard.

Loading…

Wildcard domains​

If you bring your own wildcard domain, e.g. *.example.com, you will need to create a second CNAME record with your domain host for wildcard TLS Certificate provisioning.

Apex domains​

Because it's not possible to create CNAME records for apex domains, if you want to use an apex domain, e.g. example.com, you must use a DNS provider that supports an ALIAS record or CNAME flattening.

Because of how ALIAS/CNAME flattening is implemented, apex domains will not take advantage of the Global Load Balancer. If you're trying to create your apex domain because you need to create endpoints for multiple subdomains, use a wildcard domain instead.

Using custom domains with TCP endpoints​

Public TCP endpoints are assigned randomly on an ngrok-controlled hostname with a randomly-assigned port. You may not choose the hostname and you may not select the port.

You may, however, 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:

Loading…

And then you can access that TCP endpoint with:

Loading…