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 configurationfile.
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 |
Daemonize as a background service
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
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 startngrok service stopngrok service restartngrok service uninstall
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 dyanmic set of IP Addresses.
connect.ngrok-agent.com:443
You can customize the agent ingress address to brand it with your own domain.
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.8and8.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.
Heartbeating
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 heartbeating 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 platfom, 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 |
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.
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.
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:
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.