Skip to main content
When the ngrok Agent CLI and Agent SDKs start, they establish long-lived TLS connections to the ngrok service through which they create new endpoints and receive connections from ngrok’s cloud service that are intended for your upstream services.

​
Address

By default, the latest ngrok Agent CLI dials the following Connect URL when it connects to the ngrok service. This address resolves to a dynamic set of IP Addresses.
All connections to ngrok servers are made on port 443.
You can customize the Connect URL to brand it with your own domain. By default, the agent connects to one region. It can also connect to several at once and load balance traffic across them. Contact Sales to turn this on. The complete list of addresses and IP addresses available for the agent to connect to ngrok can be found in the ngrok DNS tunnel.json file.
Prior to ngrok agent version 3.3.0, the ngrok agent connected to tunnel.*.ngrok.com domains. The latest agent uses connect.*.ngrok-agent.com domains.

​
Additional URLs

In addition to the addresses used for connecting to the ngrok server, the ngrok agent may reach out to the following URLs.

​
Certificate revocation list (CRL) check

The ngrok agent reaches out to the following domains to check for revoked certificates. This check can be disabled by adding crl_noverify: true to your ngrok agent config.
  • Prior to ngrok agent version 3.10.0: http://crl.ngrok.com/ngrok.crl
  • Latest versions: http://crl.ngrok-agent.com/ngrok.crl
These connections use HTTP and port 80.
You can download and decode the CRL using OpenSSL: openssl crl -inform PEM -text -noout -in ngrok.crl

​
ngrok Agent update check

The ngrok agent will automatically look for updates when it starts up. This check can be disabled by adding update_check: false to your ngrok agent config.
  • https://update.equinox.io
Equinox is fully owned by ngrok and used exclusively for building and distributing ngrok binaries. See the FAQ page for more details.

​
DNS resolution

When the ngrok agent dials the ngrok service to establish its TLS connections, it resolves DNS for the connection address which is defined by the connect_url configuration property. ngrok attempts to resolve DNS using multiple mechanisms so that it can establish connectivity even in network environments where DNS service is failing. ngrok attempts to resolve the IPs of its service using the following mechanisms: Instead of using the system’s default DNS resolvers, you can configure the DNS servers the ngrok agent uses for resolution with the dns_resolver_ips configuration option.

​
TLS verification

The ngrok agent connects to the ngrok service over TLS connections. The agent verifies the TLS Certificate returned by the ngrok service. The certificates returned by the ngrok service are signed by ngrok’s own root certificate authority. The ngrok agent verifies the returned certificate against certificate authorities bundled into the agent itself. Lastly, the ngrok agent makes a request to crl.ngrok-agent.com to verify that the certificate returned by the ngrok service has not been revoked. It is possible to skip this step by setting crl_noverify: true in your configuration file.

​
Heartbeats

Once the ngrok agent has established connectivity to the ngrok service, it periodically sends application-level heartbeat messages to validate the liveness of the connection. You may customize this behavior via the heartbeat_interval and heartbeat_tolerance configuration parameters. If the ngrok agent doesn’t receive a response to its heartbeat within the tolerance window, it terminates the connection and begins reconnecting. ngrok’s heartbeat mechanism allows it to recover from any type of network outage, even those caused by packet loss, dynamic IP changes, interface changes (for example, Wi-Fi to LTE) or complete network outages. The ngrok service also sends its own heartbeats to the agent which it uses to detect liveness and terminate dead connections.

​
Reconnection

If the ngrok agent is disconnected for any reason, it will automatically begin reconnecting. Reconnecting begins the entire connection process over again, beginning with DNS resolution. The ngrok agent attempts to recover quickly and slowly backs off its reconnection attempts but always attempts to re-establish connectivity unless the ngrok service explicitly instructs it to stop reconnecting.

​
Troubleshooting

If the agent can’t reach ngrok it’s often hard to tell why, because any of the steps above could be the one that failed. The ngrok diagnose command works through them in order and reports which one broke.
The ngrok diagnose command runs a series of tests to diagnose potential connectivity issues between the ngrok agent and the remote ngrok service. See available flags here.

​
Diagnostics

The diagnose command gathers your environment information, including your sanitized configuration file. It then tests:
  • proxy connectivity, if proxy_url is configured
  • name resolution
  • general internet connectivity
By default, ngrok diagnose tests IPv4 connectivity between the ngrok agent and the closest ngrok point of presence. To test IPv6 connectivity, add --ipv6 true to the command. To test connectivity between the ngrok agent and all ngrok points of presence, add --region all.

​
Basic output

The diagnose command prints a connectivity summary in your terminal. If you have full connectivity, your report will look like this:
If there’s a connectivity problem, your report will show warnings and errors that need to resolved before ngrok can work correctly:

​
Verbose output

For more detailed output, you can use the --write-report/-w flag to generate a verbose report:
By default, ngrok diagnose --region all will generate a report. The diagnose output will print the report location:

​
Kubernetes

You can run ngrok diagnose within your Kubernetes cluster to troubleshoot network connectivity issues. See Testing in a Kubernetes Cluster.