Domains + TCP Addresses

Domains

Domain objects enable you to create Endpoints to listen for traffic on those domain names. Domains may be a subdomain of an ngrok-managed base domain like foo.ngrok.app or you can bring your own branded domain like foo.example.com.

The ngrok edge accelerates traffic to endpoints on your domains by receiving it on all of our global points of presence via Global Server Load Balancing.

Once you have created a Domain object, your account exclusively owns that domain and all of its nested subdomains. For instance, if you have created a domain, foo.ngrok.app, no other account is permitted to create bar.foo.ngrok.app.

Ephemeral domains

If you run create an endpoint via the Agent or Agent SDKs without specifying a domain, ngrok will automatically assign a random domain on one of our ngrok-managed Domains to your endpoint. For example, the command ngrok http 80 may create an endpoint like https://1eb2-181-80-12-3.ngrok.app.

ngrok-managed Domains

If you don't own a domain that you want to use with ngrok, we have multiple base domains that you can claim your own subdomain of. These 'ngrok-managed' base domains are:

Domain	Notes
ngrok.app	Available to paying accounts
ngrok.dev	Available to paying accounts
ngrok-free.app	Used by free accounts
ngrok-free.dev	Used by free accounts
ngrok.io	Discontinued and only available to legacy accounts

All of the above domains are included on the Public Suffix List. Modern browsers use the Public Suffix List to guarantee that cookies from one subdomain cannot be accessed by other subdomains.

Branded Domains

You can use any domain that you already own (e.g. app.your-domain.com) with ngrok. In order to do so, you must create a CNAME record for that domain to point it at the ngrok edge. When you create the ngrok Domain object, you will be presented with a target value for the CNAME record you need to create. If you create the Domain via API, this value is the cname_target field.

If you want to use an apex domain (e.g. example.com) with ngrok, you must use a DNS provider that supports an ALIAS record or CNAME flattening. This is because the DNS RFC does not permit CNAMEs for apex domains. Because of how ALIAS/CNAME flattening is implemented, apex domains can not take advantage of Global Server Load Balancing.

Apex Domain

It is possible to reserve your apex domain, sometimes referred to as a domain apex (i.e. example.com), using the ngrok dashboard or API. However, you will need to create a CNAME record in place of your A record, which not all DNS providers support. If you are trying to reserve your apex domain because you need to create endpoints for multiple subdomains, you should use a wildcard domain instead.

Wildcard Domains

You may also create a wildcard domain on your ngrok account. For example, *.example.com. Wildcard domains allow you to create endpoints that receive traffic for all subdomains of that domain. Both HTTP and TLS endpoints support the use of wildcard domains. The wildcard * 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.

You may create wildcard domains on ngrok managed domains. You must first reserve an ngrok domain like example.ngrok.app first. You can then reserve a second domain that is a wildcard domain from your base domain, like *.example.ngrok.app.

Once you have created a wildcard domain object, you may create an endpoint on it via the Agent or attach it to an Edge. For example:

Listen for all subdomains of example.com

ngrok http 80 --domain *.example.com

The following rules define the behavior of endpoints on wildcard domains. To illustrate the rules, assume you have created the wildcard domain *.example.com:

• Connections to nested subdomains (e.g. foo.bar.baz.example.com) will route to a wildcard endpoint of *.example.com.
• You may create endpoints on any valid subdomain of example.com without creating an additional Domain object. For example, ngrok 80 http --domain foo.bar.baz.example.com works without creating a domain for foo.bar.baz.example.com.
• Connections are routed to the most specific online endpoint. If there are endpoints for both app.example.com and *.example.com, connections to app.example.com will be sent to the app.example.com endpoint and not to `*.example.com.

HSTS

ngrok's managed domains that are on the .dev or .app TLDs are on the global HSTS preload list. This means that domains on ngrok.app, ngrok.dev, ngrok-free.app, etc. require the use of HTTPS.

ngrok currently still allows you to create endpoints with an http scheme, but all modern browsers will automatically force the use of a corresponding https endpoint.

If you need to use the unencrypted http scheme, you should continue to use the domains on the ngrok.io base domain.

TCP Addresses

TCP Addresses are a network address: a host and port. You may use TCP addresses to deliver applications via TCP endpoints. TCP Address look something like 1.tcp.eu.ngrok.io:12345.

note

TCP endpoints are only available on a free plan after adding a valid payment method to your account.

You may provision TCP addresses via API.

Ephemeral addresses

If you do not specify a TCP address when creating an endpoint from the agent, a random one is assigned to you. For example, if you run ngrok tcp 22, you will receive a randomly assigned TCP address each time.

Fixed addresses

The hostname and port of the TCP Address is randomly assigned when you create it, after which it will not change. You may not choose the hostname or port. The port of your TCP address is uniquely assigned to your account, but other ports on that same hostname may be assigned to other accounts. While the hostname and port of a TCP Address is fixed, they do not have static IPs.

GSLB support

TCP Addresses do not support global server load balancing, but TCP addresses provisioned in one region can be served by agents connected to any other region.

For example, if your TCP address is 1.tcp.eu.ngrok.io:12345 you can invoke the ngrok agent by omitting the region, which will automatically connect you to the best region for you, even if it doesn't match the region in the TCP address:

ngrok tcp 22 --remote-addr 1.tcp.eu.ngrok.io:12345