Agent Config Version 3

The ngrok agent supports an optional, YAML configuration file which enables you to configure advanced settings and run multiple endpoints simultaneously.

The agent configuration file location depends on your system. You can check the location of your configuration file by running ngrok config check or edit the file in your terminal by running ngrok config edit.

Breaking Changes

There are important differences between the v3 ngrok Agent Configuration file and v2:

Agent configuration options are no longer top-level, they are now nested under the agent field.
Endpoints are now configured through the endpoints field.
Deprecated the tunnels field in favor of endpoints.
Changed server_addr agent configuration field to connect_url.
Changed root_cas agent configuration field to connect_cas.

Migrating from v2

Migrating from v2 to v3 requires you to update to the latest agent, nest your agent configuration options under the agent field and change the version field to 3 as well as modify any agent configuration fields that have changed.

For example, here is an example v2 configuration file:

version: 2
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN

tunnels:
  basic:
    proto: http
    addr: 80

For v3, you need to update the version and introduce the agent field:

version: 3

agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
  api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN

tunnels:
  basic:
    proto: http
    addr: 80

You will also need to adjust the following fields if you are using them:

Change root_cas to connect_cas
Change server_addr to connect_url

Supported Fields

The ngrok Agent Configuration file supports the following top-level configuration fields:

Configuration File Version Field - version (required)
Agent Configuration Field - agent (required)
Endpoint Definitions - endpoints
Tunnel Definitions - tunnels (deprecated)

Version

The top-level version field is required. Value must be 3.

Example

version: 3

Agent Configuration

The top-level agent field is required. The agent field allows you to modify both general and advanced agent configuration options, everything from your authtoken to whether the agent should check for updates.

Agent Configuration Options

Name	Description
`api_key`	The API key to be used when making requests through the `ngrok api` command.
`authtoken`	The authentication token used to authenticate this agent when it connects to the ngrok service.
`connect_cas`	The root certificate authorities used to validate the TLS connection to the ngrok server.
`connect_interface`	Set the specific network interface for ngrok to use. This is only supported on Linux platforms.
`connect_timeout`	How long to wait when establishing an agent session connection to the ngrok service. The default is 10s.
`connect_url`	This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL.
`console_ui`	Enable/disable the console UI
`console_ui_color`	Set the background color of the console UI
`crl_noverify`	Disables verifying Certificate Revocation List
`dns_resolver_ips`	Consult these DNS servers for tunnel session DNS resolution.
`heartbeat_interval`	How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. Default is 10s.
`heartbeat_tolerance`	Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. Default is 15s.
`inspect_db_size`	The size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay.
`log_level`	Logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`.
`log_format`	Format of written log records.
`log`	Write logs to this target destination.
`metadata`	Opaque, user-supplied string that will be returned as part of the ngrok API response to the list online sessions resource for all endpoints started by this agent.
`proxy_url`	URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection.
`remote_management`	Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`.
`update_channel`	The update channel determines the stability of released builds to update to. Use `stable` for all production deployments.
`update_check`	This tells the ngrok agent if it should check for updates. Defaults to `true`.
`web_addr`	Network address to bind on for serving the local web interface and api.
`web_allow_hosts`	`Host` headers to allow access for on the local web interface and api, can be a combination of IP's, CIDR ranges, and/or hostname suffixes.

`authtoken`

The authentication token used to authenticate this agent when it connects to the ngrok service. You can obtain your default authtoken through the ngrok Dashboard.

Deploying on Multiple Devices

Your default authtoken will work on multiple machines or devices. However, if you want more control and security across many devices, you can generate a unique authtoken for each device in the ngrok Dashboard or via the ngrok api credentials command.

Example

agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

`api_key`

note

This option is only required when you want to make requests using the ngrok api command and should not be confused with the authtoken option.

The API key to be used when making requests through the ngrok api command. You can obtain and manage your API Keys through the ngrok Dashboard.

Example

agent:
  api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN

`connect_cas`

This is the root certificate authorities used to validate the TLS connection to the ngrok server.

Parameter	Default	Description
`trusted`	default	use only the trusted certificate root for the ngrok.com tunnel service
`host`		use the root certificates trusted by the host's operating system. This is helpful for working with machine-in-the-middle (MITM) proxies doing deep packet inspection (DPI).
other values		path to a certificate PEM file on disk with certificate authorities to trust

`connect_interface`

Sets the specific network interface that the ngrok agent should use. This is only supported on Linux platforms.

`connect_timeout`

How long to wait when establishing an agent session connection to the ngrok service. This is specified as a duration, with the default being 10s.

`connect_url`

This is the URL of the ngrok server to connect to. You should set this if you are using a custom ingress URL.

`console_ui`

This option allows you to enable or disable the console UI that is displayed in your terminal window after starting ngrok.

Parameter	Default	Description
`true`		Enable the console UI
`false`		Disable the console UI
`iftty`	default	Enable the UI only if standard out is a TTY (not a file or pipe)

`console_ui_color`

The command sets the background color when displaying the console UI in the terminal. To choose a color other than black, set the value to transparent and change the background of your terminal window.

Parameter	Default	Description
`transparent`		Don't set a background color when displaying the console UI
`black`	default	Set the console UI's background to black

`crl_noverify`

This option will skip verifying with the Certificate Revocation List if set to true. This defaults to false.

`dns_resolver_ips`

Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent will use the local system DNS servers to resolve.

`heartbeat_interval`

How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. The default is 10s.

`heartbeat_tolerance`

Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. The default is 15s.

`inspect_db_size`

This is the upper limit in bytes on memory to allocate when saving requests over HTTP endpoints for inspection and reply. The default is 0, which means 50MB.

Parameter	Default	Description
positive integers		size in bytes of the upper limit on memory to allocate to save requests over HTTP endpoints for inspection and replay.
`0`	default	use the default allocation limit, 50MB
`-1`		disable the inspection database; this has the effective behavior of disabling inspection for all tunnels

`log_level`

This is the logging level of detail. In increasing order of verbosity, possible values are: crit, warn, error, info, and debug.

`log_format`

This is the format of written log records.

Parameter	Default	Description
`logfmt`		human and machine friendly key/value pairs
`json`		newline-separated JSON objects
`term`	default	custom colored human format if standard out is a TTY, otherwise same as `logfmt`

`log`

This is the destination where ngrok should write the logs.

Parameter	Default	Description
`stdout`		write to standard out
`stderr`		write to standard error
`false`	default	disable logging
`<path>`		write log records to file path on disk

agent:
  log: /var/log/ngrok.log

`metadata`

This is a user-supplied custom string that will be returned as part of the ngrok API response to the list online sessions resource for all endpoints started by this agent. This is a useful mechanism to identify endpoints by your own device or customer identifier. Maximum 4096 characters.

agent:
  metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66

`proxy_url`

This is the URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. Many HTTP proxies have connection size and duration limits that will cause ngrok to fail. Like many other networking tools, ngrok will also respect the environment variable http_proxy and http_proxy_env if it is set.

`remote_management`

Set this to true to allow the ngrok agent to be remotely managed (stop, restart, update) via the ngrok API or the ngrok Dashboard. Defaults to true.

`update_channel`

The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments.

Parameter	Default	Description
`stable`	default	These are builds that are ready to be used in production.
`unstable`		update to new nightly builds when available which could be broken. This should not be used in production.
`beta`		update to new beta builds when available which could be broken. This should not be used in production.

`update_check`

This tells the ngrok agent if it should check for updates. Defaults to true.

`web_addr`

This is the network address to bind on for serving the local agent web interface and API.

Network address		Bind to this network address
`127.0.0.1:4040`	default	default network address
`false`		disable the web UI

`web_allow_hosts`

These are a list of specifiers for what Host headers will be allowed to make requests agains the local agent web interface and API. Any port is stripped off the Host header before matching is performed.

Allow string		Example `Host` headers that would match
	default	requests to localhost-bound web interface or API endpoints are checked to have a localhost-like `Host` (localhost, 127.0.0.1, ::1, etc.)
`8.8.8.8`		an IP matches `Host` header (`8.8.8.8`)
`1:2:3:4:5:6:7:8`		an IPv6 matches `Host` header (`1:2:3:4:5:6:7:8`)
`10.0.0.0/8`		a CIDR range matches a `Host` header that is an IP address in that range (`10.0.0.1 or 10.1.2.3`)
`1:2:3:4:5:6:7:8/16`		a CIDR range matches a `Host` header that is an IPv6 address in that range (`1:2:3:4:5:6:7:0`)
`example.com`		a hostname without preceding period will match `Host` header exactly (`example.com`)
`.example.com`		a hostname with a preceding period `Host` header suffix (`sub.example.com` or `foo.example.com`)

Example

Allow an IP address and a domain as Host headers:

agent:
  web_allow_hosts:
    - 8.8.8.8
    - example.com

Endpoint Definitions

The endpoints field enables you to define and configure multiple endpoints.

Defining multiple endpoints this way enables you to start pre-configured endpoints by name without having to memorize the right arguments every time through the ngrok start command. You can also use this field to start multiple endpoints at the same time from a single agent using the ngrok start --all flag.

The endpoints field accepts a list of endpoint configurations, the list of available endpoint configuration options can be found here.

Example

In the snippet below we are defining two endpoints named 'httpbin' and 'demo':

endpoints:
  - name: httpbin
    url: https://alan-httpbin.ngrok.dev
    upstream:
      url: 8080
  - name: demo
    url: https://demo.inconshreveable.com
    upstream:
      url: 8181

Start the endpoint named 'httpbin'

ngrok start httpbin

Start all endpoints

ngrok start --all

Endpoint Configuration Options

Name	Required	Description
`name`	Required	A unique name for this endpoint's configuration.
`url`		The address you would like to use to forward traffic to your upstream service. Leave empty to get a randomly assigned address.
`metadata`		An arbitrary string of user-defined metadata for this endpoint.
`description`		An arbitrary user-defined description about this endpoint.
`traffic_policy`		Accepts a Traffic Policy configuration in YAML format.
`upstream`	Required	Upstream service configuration options.
`upstream.url`	Required	The address you would like to forward traffic to.
`upstream.protocol`		The application layer protocol the agent should use when talking to your upstream application for HTTP endpoints. Accepted values are `http1` (default) and `http2`.
`upstream.proxy_protocol`		The version of PROXY protocol to use with this endpoint, empty if not using. Example values are `1` or `2`.

`name`

Required. String. A unique name for this endpoint's configuration.

This is the value you use when running the ngrok start <name> command.

Example

# ...
endpoints:
  - name: example
# ...

`url`

String. The address you would like to use to forward traffic to your upstream service.

Accepted formats:

Domain - example.org
- When using the domain format you are only defining the domain. The scheme and port will be inferred.
Origin - https://example.ngrok.app or https://example.ngrok.app:443
- When using the origin format you are defining the protocol, domain and port.
Scheme (shorthand) - https://
- When using scheme you are defining the protocol and will receive back a randomly assigned ngrok address.
Empty - ``
- When empty your endpoint will default to be https and receive back a randomly assigned ngrok address.

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
# ...

`metadata`

String. An arbitrary string of user-defined metadata for this endpoint. This value will appear on the endpoint object in the ngrok API.

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
# ...

`description`

String. An arbitrary user-defined description about this endpoint. This value will appear on the endpoint object in the ngrok API.

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
    description: "our example application"
# ...

`traffic_policy`

Object. Accepts a Traffic Policy configuration in YAML format.

Traffic Policy enables you to manage, route and secure traffic through configuration. You can learn more about the individual parts of the Traffic Policy and the available actions here:

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
    description: "our example application"
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                content: hello, traffic policy!
                headers:
                  content-type: text/plain
# ...

`upstream`

Name	Required	Description
`upstream.url`	Required	The address you would like to forward traffic to.
`upstream.protocol`		The application layer protocol the agent should use when talking to your upstream application for HTTP endpoints. Accepted values are `http1` (default) and `http2`.
`upstream.proxy_protocol`		The version of PROXY protocol to use with this endpoint, empty if not using. Possible values are `1` or `2`.

`upstream.url`

String. The local or remote address you would like to incoming traffic to be forwarded to.

Accepted formats:

Origin - https://example.org or http://example.org:80 or tcp://127.0.0.1:80
- When using the origin format you are defining the protocol, domain and port.
  - When no port is present and scheme is https or http the port will be inferred.
    - For https port will be443.
    - For http port will be 80.
Domain - example.org
- This is only allowed for https and http endpoints.
  - For tcp and tls endpoints host and port is required.
- When using the domain format you are only defining the host.
  - Scheme will default to http.
  - Port will default to 80.
Scheme (shorthand) - https://
- This only works for https and http.
  - For tcp and tls host and port is required.
- When using scheme you are defining the protocol and the port will be inferred on the local host.
  - For https port will be443.
  - For http port will be 80.
  - Host will be localhost.
Port (shorthand) - 8080
- When using port you are defining the port on the local host that will receive traffic.
  - Scheme will default to http.
  - Host will default to localhost.

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
    description: "our example application"
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                content: hello, traffic policy!
                headers:
                  content-type: text/plain
    upstream:
      url: 8080
# ...

`upstream.protocol`

String. The application layer protocol the agent should use when talking to your upstream application for HTTP endpoints.

Accepted Values:

http1 (default)
http2

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
    description: "our example application"
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                content: hello, traffic policy!
                headers:
                  content-type: text/plain
    upstream:
      url: 8080
      protocol: http1
# ...

`upstream.proxy_protocol`

String. The version of PROXY protocol to use with this endpoint, empty if not using.

Possible values are 1 or 2.

Example

# ...
endpoints:
  - name: example
    url: https://example.ngrok.app
    metadata: '{ "id": "example-app" }'
    description: "our example application"
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                content: hello, traffic policy!
                headers:
                  content-type: text/plain
    upstream:
      url: 8080
      protocol: http1
      proxy_protocol: 2
# ...

Tunnels (Deprecated)

v3 still supports the tunnels configuration field. This is a key-value list of tunnel name to configurations.

An example can be found below:

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Tunnel Configurations
tunnels:
  basic:
    proto: http
    addr: 80

Tunnel Configuration Options

You can find the configuration options for tunnels under the Agent Configuration v2 docs.

Example Configuration Files

Below are a collection of different agent configurations to serve as examples for your ngrok.yml file.

Basic

Here is a basic example configuration file, in this example we are authenticating using our authtoken and defining a single HTTPS endpoint named basic with a endpoint url basic.ngrok.app and an upstream url of localhost:8080.

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Endpoint Definitions
endpoints:
  - name: basic
    url: basic.ngrok.app
    upstream:
      url: 8080

Starting the `basic` endpoint

Run the following command to start the basic endpoint. Make sure you update the authtoken in the example to your own before running the following command:

ngrok start basic

Multiple Endpoints

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration. Required.
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Endpoint Definitions
endpoints:
  - name: foo
    description: foo123
    metadata: foo123
    url: foo.ngrok.io
    upstream:
      url: 8080
      protocol: http1
  - name: bar
    url: bar.ngrok.io
    upstream:
      url: 8080

Endpoint with Inline Traffic Policy

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration. Required.
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Endpoint Definitions
endpoints:
  - name: foo
    description: foo123
    metadata: foo123
    url: foo.ngrok.io
    # Traffic Policy that will be applied to this endpoint
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                content: hello, traffic policy!
                headers:
                  content-type: text/plain
    upstream:
      url: 8080
      protocol: http1

Endpoint with Traffic Policy File

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration. Required.
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Endpoint Definitions
endpoints:
  - name: bar
    url: bar.ngrok.io
    # Path to the traffic policy to be read and applied to this endpoint
    traffic_policy_file: /path/to/your/traffic-policy.yml
    upstream:
      url: 8080
      protocol: http2

Endpoint with a random address

Here is an example configuration where ngrok will randomly assign your endpoint an ngrok branded address:

# Version of the ngrok Agent Configuration file. Required.
version: 3

# Agent Configuration. Required.
agent:
  authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# Endpoint Definitions
endpoints:
  # Endpoint with no endpoint url defined to get a randomly assigned ngrok address.
  - name: my_tunnel_name
    #url: http://  # uncomment this line if you want your endpoint to be HTTP, by default it's HTTPS
    upstream:
      url: 80

Breaking Changes​

Migrating from v2​

Supported Fields​

Version​

Example​

Agent Configuration​

Agent Configuration Options​

authtoken​

Deploying on Multiple Devices​

Example​

api_key​

Example​

connect_cas​

connect_interface​

connect_timeout​

connect_url​

console_ui​

console_ui_color​

crl_noverify​

dns_resolver_ips​

heartbeat_interval​

heartbeat_tolerance​

inspect_db_size​

log_level​

log_format​

log​

metadata​

proxy_url​

remote_management​

update_channel​

update_check​

web_addr​

web_allow_hosts​

Example​

Endpoint Definitions​

Example​

Start the endpoint named 'httpbin'​

Start all endpoints​

Endpoint Configuration Options​

name​

Example​

url​

Accepted formats:​

Example​

metadata​

Example​

description​

Example​

traffic_policy​

Example​

upstream​

upstream.url​

Accepted formats:​

Example​

upstream.protocol​

Accepted Values:​

Example​

upstream.proxy_protocol​

Example​

Tunnels (Deprecated)​

Tunnel Configuration Options​

Example Configuration Files​

Basic​

Starting the basic endpoint​

Multiple Endpoints​

Endpoint with Inline Traffic Policy​

Endpoint with Traffic Policy File​

Endpoint with a random address​

Breaking Changes

Migrating from v2

Supported Fields

Version

Example

Agent Configuration

Agent Configuration Options

`authtoken`

Deploying on Multiple Devices

Example

`api_key`

Example

`connect_cas`

`connect_interface`

`connect_timeout`

`connect_url`

`console_ui`

`console_ui_color`

`crl_noverify`

`dns_resolver_ips`

`heartbeat_interval`

`heartbeat_tolerance`

`inspect_db_size`

`log_level`

`log_format`

`log`

`metadata`

`proxy_url`

`remote_management`

`update_channel`

`update_check`

`web_addr`

`web_allow_hosts`

Example

Endpoint Definitions

Example

Start the endpoint named 'httpbin'

Start all endpoints

Endpoint Configuration Options

`name`

Example

`url`

Accepted formats:

Example

`metadata`

Example

`description`

Example

`traffic_policy`

Example

`upstream`

`upstream.url`

Accepted formats:

Example

`upstream.protocol`

Accepted Values:

Example

`upstream.proxy_protocol`

Example

Tunnels (Deprecated)

Tunnel Configuration Options

Example Configuration Files

Basic

Starting the `basic` endpoint

Multiple Endpoints

Endpoint with Inline Traffic Policy

Endpoint with Traffic Policy File

Endpoint with a random address