ngrok Agent

Overview

The ngrok agent is a lightweight command-line program that forwards traffic from endpoints it creates on the ngrok edge to your upstream application services.

The ngrok agent is a standalone native executable with zero runtime dependencies. It runs on all major operating systems and it is packaged for distribution on most popular package managers.

The ngrok agent uses a simple YAML configuration file, can install itself as a native operating system service and also has a built-in CLI for calling the ngrok API.

Install

Follow the getting started guide or visit the download page to install and set up the ngrok agent.

Example Usage

HTTP Endpoint

Serve your web app listening at port 8080 on a random public URL

ngrok http 8080

Static Domain

Serve a web app on example.ngrok.app

ngrok http 80 --domain example.ngrok.app

Basic Auth

Secure your web app with a username + password

ngrok http 80 --basic-auth "username1:password1" --basic-auth "username2:password2"

Forward to non-local

Forward to a service not listening on localhost

ngrok http 192.168.1.2:80

Local HTTPS Server

Forward to an upstream service listening for https

ngrok http https://localhost:8443

TCP Endpoint

Accept traffic to a non-HTTP service.

ngrok tcp 22

TLS Endpoint

Listen on your-name.ngrok.app for TLS traffic. It could be HTTPS, but any protocol wrapped in TLS is accepted.

ngrok tls 80 --terminate-at edge --domain your-name.ngrok.app

Multiple Endpoints

Start multiple tunnels defined in the configuration file.

ngrok start foo bar baz

Tab Completion

The ngrok agent has built-in tab completion which makes it easy to navigate its command and flags by hitting tab in your terminal when using a bash or zsh shell. Add tab-completion to your shell session with:

. <(ngrok completion>

Install it permanently by following the documentation for the ngrok completion command.

Authtokens

The ngrok agent authenticates with an authtoken. Your authtoken is available on the ngrok dashboard. Add your authtoken to the ngrok agent with the following command:

ngrok config add-authtoken <TOKEN>

This command updates the authtoken property in your ngrok configuration file.

Use a separate authtoken for each agent you configure. You can provision additional authtokens on your ngrok dashboard or via API. Separate authtokens isolate the security risk if an authtoken is compromised. It also allows you to configure ACLs on a per agent basis.

When you provision a new authtoken, the full token is only displayed once. As a security feature, ngrok does not store a recoverable representation of the token.

Authtoken ACLs

Authtoken ACLs restrict what actions an ngrok agent connecting with that authtoken is allowed to take. You may define multiple ACLs. Authtokens with no ACLs may take all actions. The following ACLs are supported:

Example	Description
bind:foo.ngrok.app	The agent may only create an endpoint on foo.ngrok.app
bind:*.example.com	The agent may only create endpoints on subdomains of example.com
bind:foo=bar	The agent may create a labeled tunnel with the label foo=bar
bind:app=*	The agent may create labeled tunnels with labels like app=x or app=y
bind:*	The agent may listen on all endpoints

API Keys

The ngrok agent contains a complete CLI for the ngrok API.

To use it, create an API Key on your ngrok dashboard and then run:

ngrok config add-api-key <API KEY>

After you've installed the API Key, try querying your list of domains or online endpoints:

ngrok api endpoints list
ngrok api reserved-domains list

Configuration File

The ngrok agent uses a YAML configuration file to customize its behavior. The config file is useful if your configuration is too complex for the command line and if you want the agent to run multiple tunnels simultaneously.

Consult the ngrok agent configuration file reference for a full list of configuration file options.

Environment Variables

The ngrok agent supports environment variables for some configuration. Environment variables take precedence over the corresponding values specified in the configuration file.

Name	Configuration Property
NGROK_AUTHTOKEN	authtoken
NGROK_API_KEY	api_key

Running ngrok in the background

ngrok includes commands to run itself in the background as a native operating system service, i.e. as a daemon. When it runs as an operating system service it:

• Starts when the machine boots
• Automatically restarts after crashes
• Can be managed via native OS service tooling
• Sends logs to the OS's native logging service
• Starts all tunnels defined in the configuration file, the equivalent of running ngrok start --all

tip

In most cases, installing ngrok as a service requires administrator privileges.

OS	Notes
Linux	The ngrok agent creates a systemd unit file. Errors and warnings are logged to syslog.
Windows	The ngrok agent installs itself as a Windows service. It can be managed via Windows Services. Errors and warnings are logged to the Windows event log.
MacOS	The ngrok agent creates a plist file and configures itself to run via launchd. Errors and warnings are logged to syslog.

Try it out

Create an ngrok configuration file. For this example, we'll assume it's C:\ngrok\ngrok.yml. In your configuration file, make sure you include the authtoken property and define all of the tunnels that you want to start. Then run:

ngrok service install --config C:\ngrok\ngrok.yml

This will validate that the configuration file is valid, and if so, install ngrok as a service using the given configuration file. The service installation includes the location of the ngrok executable and the configuration file, so don't move or delete either after you've installed the service.

You can then start the ngrok agent service with:

ngrok service start

You can manage the agent with your OS's normal service tooling, but the agent also includes the ngrok service commands to manage the installed service:

• ngrok service start
• ngrok service stop
• ngrok service restart
• ngrok service uninstall

tip

If you see an exit code 5 or Input/output error, it usually indicates that ngrok is not able to find the config file and/or does not have permissions to do so. Make sure you have installed the ngrok service with a valid config file and that when the service is run (either as you or an administrator) it has access to that same config file.

Remote Management

The ngrok agent can be stopped, restarted, or upgraded remotely using the Tunnel Sessions API. You can also perform these actions from the ngrok Dashboard.

warning

Use this with caution if you have made changes to the config file. If for some reason ngrok cannot restart, you may lose access to the agent completely.

Connectivity

When the ngrok agent 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 edge that are intended for your upstream services.

Address

By default, the ngrok agent dials the following "agent ingress address" when it connects to the ngrok service. This address resolves to a dynamic set of IP Addresses.

connect.ngrok-agent.com:443

You can customize the agent ingress address to brand it with your own domain.

The agent by default only connects to a single region. However connections to multiple regions can be created with traffic load balanced across these connections. If you are interested in this capability, please contact us.

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 server_addr 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:

• Via the system's default DNS resolvers
• Via Google's DNS servers (8.8.8.8 and 8.8.4.4)
• Via Google's DNS-over-HTTPS service (https://developers.google.com/speed/public-dns/docs/doh)
• Via a file hosted on an ngrok-controlled S3 bucket

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.com to verify that the certificate returned by the ngrok service has not been revoked.

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 does not 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 (e.g. WiFi 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 ngrok agent can't connect to the ngrok service, it is often difficult to understand why.

The ngrok agent includes the ngrok diagnose command to help you troubleshoot connection failures. It runs a series of tests to diagnose potential issues when connecting to the ngrok service. Consult the ngrok diagnose documentation for additional details.

$ ngrok diagnose
  Testing ngrok connectivity...

  Internet Connectivity
    Name Resolution                           [ OK ]
    TCP                                       [ OK ]
    TLS                                       [ OK ]
  Ngrok Connectivity
    Name Resolution                           [ OK ]
    TCP                                       [ OK ]
    TLS                                       [ OK ]
    Tunnel Protocol                           [ OK ]

  Successfully established ngrok connection! (region: 'us', latency: 112.461875ms)

System Requirements

Supported Platforms

The ngrok agent runs on all major platforms including Linux, MacOS, Windows and most CPU architectures. See the ngrok agent download page. It is also distributed as a Docker container.

OS	Supported Architectures
Windows	64-bit, 32-bit (x86-64, x86)
MacOS	Intel, Apple Silicon (x86-64, arm64)
Linux	x86-64, x86, arm, arm64, mips, mips64, mips64le, mipsle, ppc64, ppc64le, s390x
FreeBSD	x86-64, x86, arm, arm64

If the agent does not run on your target platform, you can still use ngrok via the Agent SDKs or the SSH Reverse Tunnel Agent.

Resource Requirements

The ngrok agent is lightweight enough to run most everywhere, even on many embedded platforms. Keep in mind that the ngrok agent's resource usage depends on how much concurrent traffic you drive through it. If your resource requirements are more stringent, you can still use ngrok via the Agent SDKs or the SSH Reverse Tunnel Agent.

Resource	Value
Memory	64MB minimum, 128MB recommended
Disk	25MB
CPU	No requirement

tip

You can reduce memory usage in the ngrok agent by disabling inspection in the configuration file.

Updates

The ngrok agent can update itself even if you didn't install it with a package manager. Update the ngrok agent with the ngrok update command.

ngrok update

By default, the ngrok agent automatically checks for available updates when it runs. If an update is available, it will prompt you to update by pressing Ctrl+U. You can configure whether the agent checks for updates via the update_check config parameter.

You can configure which release channel (e.g. stable, beta) the agent uses for updates via the update_channel config parameter.

IP Restrictions

All agents must use an authtoken to authenticate with ngrok, but you may also further restrict with IP Policies that specify which IPs and CIDRs agents may connect to your ngrok account from.

• IP Restrictions on your ngrok dashboard
• IP Restrictions API Resource

API

The ngrok agent has its own HTTP API that can be used to dynamically inspect, start and stop tunnels on the agent while it is running. Consult the ngrok agent API reference documentation for more details.

tip

If you want to programmatically control the ngrok agent, the Agent SDKs are usually a more flexible and powerful choice.

Using ngrok without the agent

There are three ways to use ngrok without the agent:

• Agent SDKs
• Kubernetes Operator
• SSH Reverse Tunnel

You may want to use ngrok with one of the alternatives above if:

• You don't want to manage the lifetime of a separate agent process
• You don't want to bundle and distribute the ngrok agent
• The ngrok agent doesn't run on your target platform
• The ngrok agent's resource requirements are too high for your target platform
• You want fine-grained programmatic control over the agent's functionality

Changelog

We publish the ngrok agent changelog with details on each release of the ngrok agent.

Pricing

The ngrok agent is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the agent incur a cost. For more information, see the ngrok Pricing page.