Overview
Domains enable you to create public endpoints with hostnames matching the domain. For example, after you create the domainyour-name.ngrok.app, you may
create the Endpoint https://your-name.ngrok.app
Domain names may be a subdomain of an ngrok-managed
domain like foo.ngrok.app or you can bring your own
domain like example.your-domain.com by creating a CNAME
DNS record with your domain’s DNS provider.
Domains also enable you configure other domain-level behaviors including:
- Global Load Balancer configuration - Choose which points of presence handle traffic to a Domain’s matching endpoints.
- TLS Certificate management - Configure automatic certificate provisioning or select a certificate you uploaded yourself.
- Dedicated IP address configuration - Attach static, dedicated IPs for a Domain’s matching endpoints receive traffic on.
Public endpoints
A Domain’s primary responsibility is to enable you to create public endpoints with a hostname matching the domain. These are called “matching endpoints”. For example, after you create the Domainapp.example.com, you can create the Endpoint
https://app.example.com.
When you create a Domain, you may create matching public endpoints with the
following constraints:
| Endpoint Protocol | Allowed Endpoints |
|---|---|
http | Matching endpoints on port 80 of the Domain. |
https | Matching endpoints on port 443 of the Domain. |
tls | Matching endpoints on port 443 of the Domain. |
tcp | Not allowed. Public TCP endpoints must match a TCP Address. |
Dev Domains
Every ngrok account comes with a free Dev Domain that can be used if you don’t want to pick a domain. Its URL is automatically generated and cannot be changed. You can use this domain for creating a public endpoint to host your app, API, or any other service you’d like to put online. Dev domains are not billed for endpoint hours and do not count toward the domain limits of paid plans.Wildcard Domains
You may create a Domain with a wildcard name, e.g.*.example.com. A wildcard
domain enables you to:
-
Create an endpoint which receives traffic for all of its subdomains, e.g.
https://*.example.com. Consult the documentation for wildcard endpoints to understand the rules for matching and precedence. -
Create an endpoint on any subdomain which matches the wildcard, e.g.
https://foo.example.comorhttps://foo.bar.baz.example.com
* character may only be used as the first part of a
domain, you may not create domains like app.*.example.com or
*-app.example.com.
Wildcard domains are available on our Pay-as-you-go plan self service. When you create a wildcard domain and run endpoints on the subdomains (for example,
*.foo.com with endpoints https://a.foo.com and https://b.foo.com), we bill you endpoint hours for each individual endpoint, as well as custom domain hours for the wildcard domain.Reserving subdomains of a wildcard domain within the ngrok dashboard count towards the number of reserved domains in your account. For example, if you reserve
foo.example.com and *.example.com, you have reserved two domains.Random Domains
For some applications, you may not care much about the actual domain for the endpoint. Generating these can be a pain, so we’ve included an easy way to create and use these for endpoints. Using the valuehttps://${randomUrl} in the url field will generate a random url for you to use with your endpoint.
Random domain generation is only available on paid plans. The free plan is limited to your dev domain for public endpoints.
Ownership
Your account exclusively owns its Domains and all of their nested subdomains within ngrok. That means:- No account may create a Domain with a name that is a subdomain of your Domains.
- No other account may create endpoints with a hostname matching your Domain or any of its nested subdomains.
foo.ngrok.app:
- No other account create the Domains
foo.ngrok.apporbar.foo.ngrok.app. - No other account may create the endpoints
https://foo.ngrok.apporhttps://bar.foo.ngrok.app.
Bring your own domain
You can use any custom domain name that you already own with ngrok, e.g.app.your-domain.com. To do so, see the docs on using custom domains.
Global Load Balancer
The Global Load Balancer uses latency-aware DNS records to direct clients to the IPs of the nearest points of presence. Domains allow you to configure which points of presence the Global Load Balancer may resolve clients to. This allows you to select which points of presence will receive traffic for the Domain’s matching endpoints. To disable the Global Load Balancer, you may configure a domain to only resolve a single point of presence.Per-region global load balancer configuration is coming soon, request access
to the developer preview.
TLS Certificates
Domains manage the TLS Certificate used to terminate TLS connections to the Domain’s matching endpoints. When you create a Domain, you may choose to allow ngrok to automatically provision TLS certificates for you or to upload your own TLS certificate. Consult the documentation on TLS Certificates for additional details on certificate provisioning and management.Dedicated IPs
By default, a Domain’s matching Endpoints receive traffic on a set of multi-tenant IP addresses that are shared among all ngrok accounts. You may instead configure a Domain’s matching endpoints to receive traffic on IP addresses that are dedicated to your account. If your Domain uses dedicated IPs, you may create public endpoints on any port numbers, not just 80 and 443.Dedicated, static IPs for your domains are coming soon, request access to the
developer preview.
ngrok Managed Domains
If you don’t own a domain that you want to use with ngrok, you can create a Domain that is a subdomain of an ngrok-managed base domain. The ngrok-managed base domains are:| Domain | Availability | HSTS Global Preload |
|---|---|---|
ngrok.app | Available to paying accounts | Yes |
ngrok.dev | Available to paying accounts | Yes |
ngrok.pizza | Available to paying accounts | No |
ngrok-free.app | Used by free accounts | Yes |
ngrok-free.dev | Used by free accounts | Yes |
ngrok-free.pizza | Used by free accounts (coming soon) | No |
ngrok.io | Discontinued and only available to older accounts | No |
Public Suffix List
The ngrok-managed base domains are on the Public Suffix List. Browsers use the Public Suffix List to guarantee that cookies from one subdomain cannot be accessed by other subdomains.HSTS Preload
Some of the ngrok-managed base domains are on the global HSTS preload list. If the domain of the URL is on the global HSTS preload list, modern browsers automatically convert requests with anhttp scheme to https.
If you need to create unencrypted http endpoints, you should create them with
hostnames that are not on the HSTS Global Preload like ngrok.io and
ngrok.pizza.
ngrok does not prohibit you from creating http endpoints with hostnames whose
base domain is on the global HSTS preload list because non-browser clients
(like curl) can still be used to make unencrypted HTTP requests to them.
API
Domains are programmatically managed via:Pricing
Domains are available on all plans. Some Domain features require upgrades. See the Pricing page for details.| Feature | Plans |
|---|---|
| Domains | All plans. The Domain name is assigned on Free, you may choose it on other plans. |
| Bring-your-own domains | Personal, Pro, Pay-as-you-go, Pay-as-you-go |
| Wildcard Domains | Pay-as-you-go |