ngrok Agent Command Line Interface (CLI)
The ngrok agent CLI offers built-in commands for interfacing with the ngrok API. These API commands have been separated into the ngrok agent CLI API page for convenience. For more information about the ngrok API and interfacing with it directly, see see the ngrok api page.
ngrok
ngrok exposes local networked services behinds NATs and firewalls to the public internet over a secure tunnel. Share local websites, build/test webhook consumers and self-host personal services. Detailed help for each command is available by adding '--help' to any command or with the 'ngrok help' command. Open https://dashboard.ngrok.com/obs/traffic-inspector to inspect traffic.
Usage
ngrok [command] [flags]
Example
ngrok http 80 # secure public URL for port 80 web server
ngrok http --url baz.ngrok.dev 8080 # port 8080 available at baz.ngrok.dev
ngrok http foo.dev:80 # tunnel to host:port instead of localhost
ngrok http https://localhost # expose a local https server
ngrok tcp 22 # tunnel arbitrary TCP traffic to port 22
ngrok tls --url=foo.com 443 # TLS traffic for foo.com to port 443
ngrok start foo bar baz # start tunnels from the configuration file
SubCommands
| Command | Description |
|---|---|
| api | use ngrok agent as an api client |
| completion | generates shell completion code for bash or zsh |
| config | update or migrate ngrok's configuration file |
| credits | prints author and licensing information |
| diagnose | diagnose connection issues |
| http | start an HTTP tunnel |
| service | run and control an ngrok service on a target operating system |
| start | start endpoints or tunnels by name from the configuration file |
| tcp | start a TCP tunnel |
| tls | start a TLS tunnel |
| tunnel | start a tunnel for use with a tunnel-group backend |
| update | update ngrok to the latest version |
| version | print the version string |
Flags
| Flag | Description |
|---|---|
--metadata | opaque user-defined metadata for the tunnel session |
ngrok completion
The ngrok completion command generates shell tab completion code for Bash or Zsh. This requires bash-completion or zsh-completions packages to be enabled in your shell.
You can add it to your current session with the command
. <(ngrok completion)
To enable them each time you start a new session, add the following to your .bashrc or .zshrc files:
if command -v ngrok &>/dev/null; then
eval "$(ngrok completion)"
fi
Once you add this to your profile, you'll need to source ~/.bashrc or source ~/.zshrc to enable it for your current session.
Usage
ngrok completion [flags]
Example
Flags
| Flag | Description |
|---|---|
--config | path to config files; they are merged if multiple |
ngrok config
The config command gives a quick way to create or update ngrok's configuration file. Use 'add-authtoken' or 'add-api-key' to set the corresponding properties.
Use 'check' to test a configuration file for validity. If you have an old configuration file, you can also use 'upgrade' to automatically migrate to the latest version.
SubCommands
| Command | Description |
|---|---|
| add-api-key | save api key to configuration file |
| add-authtoken | save authtoken to configuration file |
| add-connect-url | adds the connect URL (connect_url) to configuration file for custom agent ingress |
| add-server-addr | alias of add-connect-url |
| check | check configuration file |
| edit | edit configuration file |
| upgrade | auto-upgrade configuration file |
Flags
| Flag | Description |
|---|---|
--config | path to config files; they are merged if multiple |
ngrok config add-api-key
The add-api-key command modifies your configuration file to include the specified api key.
The API key can be generated in the API section of the ngrok dashboard.
Usage
ngrok config add-api-key TOKEN [flags]
Example
ngrok config add-api-key 1roPsn7AascHeO18mHcxRD3xT76_3ww7C9CDLYNgcdSYsscCB
Flags
| Flag | Description |
|---|---|
--config | save in this config file |
ngrok config add-authtoken
The add-authtoken command modifies your configuration file to include the specified authtoken.
ngrok requires that you sign up for an account to use many advanced service features. In order to associate your client with an account, it must pass a secret token to ngrok when it starts up. Instead of passing this authtoken on every invocation, you may use this command to save it into your configuration file so that your client always authenticates you properly.
Additionally, this command saves the default config version, providing a working config file out of the box.
You can find your authtoken in the getting started section of the ngrok dashboard. The ngrok service requires that you sign up for an account to connect with an agent. Some advanced service features require a paid account. In order to associate your agent with an account, it must pass a secret token to the ngrok service when it starts up. Instead of passing this authtoken on every invocation, you may use this command to save it into your configuration file so that your agent always authenticates you properly.
Usage
ngrok config add-authtoken TOKEN [flags]
Example
ngrok config add-authtoken 1rlHSX3HqrqmOWZdeJ6bIv8rfuo_4cmS1QswRGyxcQD8NOukF
Flags
| Flag | Description |
|---|---|
--config | save in this config file |
ngrok config add-connect-url
The add-connect-url command modifies your configuration file to include the specified connect URL (connect_url) used for custom agent ingress.
Usage
ngrok config add-connect-url agent.example.com:443 [flags]
Example
ngrok config add-connect-url agent.example.com:443
Flags
| Flag | Description |
|---|---|
--config | save in this config file |
ngrok config add-server-addr
The ngrok config add-server-addr command updates the server address (server_addr) in the configuration file. This is useful when your account is using Custom Agent Ingress and you need to configure the server_addr to point to your new ingress domain.
See Also:
server_addr
Custom Agent Ingress
Usage
ngrok config add-server-addr agent.example.com:443 [flags]
Example
ngrok config add-server-addr agent.example.com:443
Flags
| Flag | Description |
|---|---|
--config | save in this config file |
ngrok config check
Checks a configuration file for validity/correctness.
Usage
ngrok config check [flags]
Flags
| Flag | Description |
|---|---|
--config | check this config file |
ngrok config edit
Opens the configuration file in an editor defined by the EDITOR environment variable, defaulting to nano or Notepad depending on OS.
Usage
ngrok config edit [flags]
Flags
| Flag | Description |
|---|---|
--config | check this config file |
ngrok config upgrade
Upgrade a configuration file to a version.
A backup file will be created with your original configuration file in the same directory.
You can optionally pass a version to upgrade to. If the configuration file version is missing, the upgrade command will add it. It also applies all automatic transformations when upgrading versions. Attempting to downgrade will result in an error.
By default this command will apply the transformations and display the final file. Use --dry-run to preview changes before applying.
By default this command will not move any configuration files to their new default location. Use --relocate to move the config file to the default location.
Usage
ngrok config upgrade [version] [flags]
Flags
| Flag | Description |
|---|---|
--config | upgrade this config file |
--dry-run | preview the proposed changes |
--relocate | relocates the config file to the default location |
ngrok credits
Displays program credits and license information.
Usage
ngrok credits [flags]
Flags
| Flag | Description |
|---|---|
--config | path to config files; they are merged if multiple |
ngrok diagnose
Runs a series of tests to diagnose potential connectivity issues between the ngrok agent and the remote ngrok service.
Usage
ngrok diagnose [flags]
Flags
| Flag | Description |
|---|---|
--6, --ipv6 | Enable testing of IPV6 addresses |
--r, --region | ngrok server region [auto, us, eu, au, ap, sa, jp, in, us-cal-1, eu-lon-1, all] |
--w, --write-report | Write a JSON report |
--config | path to config files; they are merged if multiple |
ngrok http
Starts a tunnel listening for HTTP/HTTPS traffic with a specific hostname. The HTTP Host header on incoming public requests is inspected to determine which tunnel it matches.
HTTPS endpoints terminate TLS traffic at the ngrok server using the appropriate certificates. The decrypted, HTTP traffic is then forwarded through the secure tunnel and then to your local server. If you don't want your TLS traffic to terminate at the ngrok server, use a TLS or TCP tunnel.
Usage
ngrok http [address:port | port] [flags]
Example
ngrok http 8080 # forward ngrok subdomain to port 80
ngrok http example.com:9000 # forward traffic to example.com:9000
ngrok http --url=bar.ngrok.dev 80 # request url name: 'bar.ngrok.dev'
ngrok http --url=example.com 1234 # request endpoint 'example.com' (DNS CNAME)
ngrok http --basic-auth='falken:joshua' 80 # enforce basic auth on tunnel endpoint
ngrok http --host-header=example.com 80 # rewrite the Host header to 'example.com'
ngrok http file:///var/log # serve local files in /var/log
ngrok http https://localhost:8443 # forward to a local https server
Flags
| Flag | Description |
|---|---|
--app-protocol (deprecated) | use --upstream-protocol instead |
--authtoken | ngrok.com authtoken identifying a user |
--basic-auth | enforce basic auth on tunnel endpoint, 'user:password' |
--binding | ingress binding for an agent endpoint |
--cidr-allow | reject connections that do not match the given CIDRs |
--cidr-deny | reject connections that match the given CIDRs |
--circuit-breaker | reject requests when 5XX responses exceed this ratio |
--compression | gzip compress http responses from your web service |
--description | user editable description about this endpoint |
--domain | host tunnel on a custom subdomain or hostname (requires DNS CNAME) |
--host-header | set Host header; if 'rewrite' use local address hostname |
--hostname (deprecated) | host tunnel on custom hostname (requires DNS CNAME) |
--inspect | enable/disable http introspection (default true) |
--metadata | metadata about this endpoint |
--mutual-tls-cas | path to TLS certificate authority to verify client certs in mutual tls |
--name | user supplied name for this endpoint |
--oauth | enforce authentication oauth provider on tunnel endpoint, e.g. 'google' |
--oauth-allow-domain | allow only oauth users with these email domains |
--oauth-allow-email | allow only oauth users with these emails |
--oauth-client-id | oauth app client id, optional |
--oauth-client-secret | oauth app client secret, optional |
--oauth-scope | request these oauth scopes when users authenticate |
--oidc | oidc issuer url, e.g. https://accounts.google.com |
--oidc-client-id | oidc app client id |
--oidc-client-secret | oidc app client secret |
--oidc-scope | request these oidc scopes when users authenticate |
--policy-file (deprecated) | use --traffic-policy-file instead |
--proxy-proto (deprecated) | use --upstream-proxy-protocol instead |
--region (deprecated) | ngrok automatically chooses the region with lowest latency |
--request-header-add | header key:value to add to request |
--request-header-remove | header field to remove from request if present |
--response-header-add | header key:value to add to response |
--response-header-remove | header field to remove from response if present |
--scheme (deprecated) | use --url instead |
--subdomain (deprecated) | host tunnel on a custom subdomain |
--traffic-policy-file | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' |
--ua-filter-allow | a list of regular expressions for user-agents to allow |
--ua-filter-deny | a list of regular expressions for user-agents to deny |
--upstream-protocol | Specify the upstream protocol to be used: 'http1', 'http2' (default 'http1') |
--upstream-proxy-protocol | version of proxy proto to use with this tunnel, empty if not unused |
--upstream-tls-verify | enables TLS verification of server TLS certificates |
--upstream-tls-verify-cas | path to CA cert to use to verify server certs |
--url | host endpoint on a URL |
--verify-webhook | validate webhooks are signed by this provider, e.g. 'slack' |
--verify-webhook-secret | secret used by provider to sign webhooks, if any |
--websocket-tcp-converter | convert ingress websocket connections to TCP upstream |
--config | path to config files; they are merged if multiple |
ngrok service
The service command manages installation and execution of ngrok as an operating system service on Windows, OS X and Linux systems. The service command takes a single argument which must be 'start', 'stop', 'restart', 'install', or 'uninstall'.
When you choose 'install', you must specify the config flag which will define where the installed ngrok service looks for its configuration file.
When the ngrok service runs, it has the same behavior as if it were invoked from the command line with the command: "ngrok start --all".
For more information about running ngrok as a service, check out the ngrok service section in the secure tunnels documentation
Usage
ngrok service [flags]
Example
ngrok service install --config=C:\ngrok.yml
ngrok service start
ngrok service stop
Flags
| Flag | Description |
|---|---|
--config | path to config files; they are merged if multiple |
ngrok start
Starts tunnels by name from the configuration file. You may specify any number of tunnel names. You may start all tunnels in the configuration file with the --all switch.
Usage
ngrok start [flags]
Example
ngrok start dev # start tunnel named 'dev' in the configuration file
ngrok start web blog # start tunnels named 'web' and 'blog'
ngrok start --all # start all tunnels defined in the config file
Flags
| Flag | Description |
|---|---|
--all | start all endpoints or tunnels in the configuration file |
--authtoken | ngrok.com authtoken identifying a user |
--none | start running no endpoints or tunnels |
--region (deprecated) | ngrok automatically chooses the region with lowest latency |
--config | path to config files; they are merged if multiple |
ngrok tcp
Starts a tunnel which forwards all TCP traffic on a public port to a local address. This is extremely useful for exposing services that run non-HTTP traffic (ssh, sip, rdp, game servers, etc).
A TCP tunnel binds a public address on the remote ngrok server. Any services which require a stable public address should use the --url option. ngrok requires that you reserve a TCP tunnel address for your account before you can use it.
TCP endpoints are only available on a free plan after adding a valid payment method to your account.
Usage
ngrok tcp [address:port | port] [flags]
Example
# forward a port to your local ssh server
ngrok tcp 22
# expose an RDP server on a specific public address that you reserved
ngrok tcp --url=1.tcp.ngrok.io:27210 3389
Flags
| Flag | Description |
|---|---|
--authtoken | ngrok.com authtoken identifying a user |
--binding | ingress binding for an agent endpoint |
--cidr-allow | reject connections that do not match the given CIDRs |
--cidr-deny | reject connections that match the given CIDRs |
--description | user editable description about this endpoint |
--metadata | metadata about this endpoint |
--name | user supplied name for this endpoint |
--policy-file (deprecated) | use --traffic-policy-file instead |
--proxy-proto (deprecated) | use --upstream-proxy-protocol instead |
--region (deprecated) | ngrok automatically chooses the region with lowest latency |
--remote-addr | bind remote address (requires you reserve an address) |
--traffic-policy-file | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' |
--upstream-proxy-protocol | version of proxy proto to use with this tunnel, empty if not unused |
--url | host endpoint on a URL |
--config | path to config files; they are merged if multiple |
ngrok tls
Starts a tunnel listening for TLS traffic on port 443 with a specific hostname. The TLS SNI (Server Name Indication) extension field in the TLS connection is inspected to determine which tunnel it matches.
The ngrok server does not terminate TLS connections forwarded with this command. Any underlying protocol may be used. You may optionally specify a TLS key/cert pair which will be used to terminate the traffic client-side before it is forwarded. If not specified, the traffic will be forwarded still encrypted.
Using this command is only recommended with the --url option. Other uses will work, but will always result in certificate mismatch warnings.
Usage
ngrok tls [address:port | port] [flags]
Example
# forward TLS traffic for example.com to port 443 (requires CNAME)
ngrok tls --url=example.com 443
# forward TLS traffic on subdomain (mismatch certificate warning)
ngrok tls 1234
# terminate TLS traffic for t.co before forwarding
ngrok tls --url=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443
Flags
| Flag | Description |
|---|---|
--authtoken | ngrok.com authtoken identifying a user |
--binding | ingress bindings for an agent endpoint |
--cidr-allow | reject connections that do not match the given CIDRs |
--cidr-deny | reject connections that match the given CIDRs |
--crt | path to a TLS certificate for TLS termination |
--description | user editable description about this endpoint |
--domain | host tunnel on a custom subdomain or hostname (requires DNS CNAME) |
--hostname (deprecated) | host tunnel on custom hostname (requires DNS CNAME) |
--key | path to a TLS key for TLS termination |
--metadata | metadata about this endpoint |
--mutual-tls-cas | path to TLS certificate authority to verify client certs in mutual tls |
--name | user supplied name for this endpoint |
--policy-file (deprecated) | use --traffic-policy-file instead |
--proxy-proto (deprecated) | use --upstream-proxy-protocol instead |
--region (deprecated) | ngrok automatically chooses the region with lowest latency |
--subdomain (deprecated) | host tunnel on a custom subdomain |
--terminate-at | terminate at ngrok "edge", "agent", or "upstream". defaults to "upstream" unless --crt or --key are present, in which case "edge" is the default. |
--traffic-policy-file | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' |
--upstream-proxy-protocol | version of proxy proto to use with this tunnel, empty if not unused |
--upstream-tls-verify | enables TLS verification of server TLS certificates |
--upstream-tls-verify-cas | path to CA cert to use to verify server certs |
--url | host endpoint on a URL |
--config | path to config files; they are merged if multiple |
ngrok tunnel
Starts a tunnel with labels so that it can be part of a tunnel-group. The tunnel-group consists of all the tunnels matching all the labels of a tunnel-group backend. Endpoint configurations containing a tunnel-group backend will cause traffic to their associated reserved domain or address to be forwarded to the tunnel-group.
See the Tunnel Group backends and Edges pages for more information.
Usage
ngrok tunnel [--label key=value] ... [address:port | port] [flags]
Example
# tunnel-group traffic for app=foo may be forwarded to port 80
ngrok tunnel --label app=foo 80
# match tunnel-group with multiple labels
ngrok tunnel --label app=foo --label dc=bar 80
Flags
| Flag | Description |
|---|---|
--app-protocol (deprecated) | use --upstream-protocol instead |
--authtoken | ngrok.com authtoken identifying a user |
--crt | path to a TLS certificate for TLS termination |
--description | user editable description about this endpoint |
--inspect | enable/disable http introspection (default true) |
--key | path to a TLS key for TLS termination |
--label | labels to associate with the tunnel in key=value format |
--metadata | metadata about this endpoint |
--mutual-tls-cas | path to TLS certificate authority to verify client certs in mutual tls |
--name | user supplied name for this endpoint |
--proxy-proto (deprecated) | use --upstream-proxy-protocol instead |
--region (deprecated) | ngrok automatically chooses the region with lowest latency |
--upstream-protocol | Specify the upstream protocol to be used: 'http1', 'http2' (default 'http1') |
--upstream-proxy-protocol | version of proxy proto to use with this tunnel, empty if not unused |
--config | path to config files; they are merged if multiple |
ngrok update
Updates ngrok to the latest version. This command checks the ngrok web service for a newer versions of the ngrok agent. If a newer version is available, it will download it an replace the ngrok binary with the new version after cryptographically verifying the update is safe to apply.
In order to update successfully, the ngrok binary must be in a directory that is writable by your current user. If you placed ngrok in a system path, you may need to run this with root or Administrator privileges.
Usage
ngrok update [flags]
Example
ngrok update - update ngrok to the latest stable version
ngrok update --channel=beta - update ngrok to the latest beta version
Flags
| Flag | Description |
|---|---|
--channel | update channel (stable, beta, unstable) |
--config | path to config files; they are merged if multiple |
ngrok version
print the version string
Usage
ngrok version [flags]
Flags
| Flag | Description |
|---|---|
--config | path to config files; they are merged if multiple |