Agent Config Version 2 - ngrok documentation

Full example

The following is a comprehensive configuration file for ngrok with detailed documentation for each option. To activate a specific option or tunnel, uncomment the relevant lines by removing the # at the beginning of the line.

# ngrok Configuration File v2
# https://ngrok.com/docs/agent/config/

# ######################################################################
# # Agent Configuration                                                #
# ######################################################################

# ----------------------------------------------------------------------
# | Authtoken (required)                                               |
# ----------------------------------------------------------------------

# Specifies the authentication token (authtoken) used to connect to the
# ngrok service.
#
#  (1) You can get your default authtoken through the dashboard:
#      https://dashboard.ngrok.com/get-started/your-authtoken
#
#  (2) You can view and generate authtokens through the dashboard
#      https://dashboard.ngrok.com/authtokens

#authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

# ----------------------------------------------------------------------
# | API Key                                                            |
# ----------------------------------------------------------------------

# The ngrok API key used to connect to the ngrok API.
#
#  (!) This is only needed when using the ngrok api command and should
#      not be confused with the authtoken.
#
#  (1) You can obtain and manage your API Keys through the dashboard:
#      https://dashboard.ngrok.com/api-keys

#api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN

# ----------------------------------------------------------------------
# | Connect Timeout                                                    |
# ----------------------------------------------------------------------

# How long to wait when establishing an agent session connection to the
# ngrok service.
#
# Accepts duration, the default is 10s

#connect_timeout: 30s

# ----------------------------------------------------------------------
# | Console UI                                                         |
# ----------------------------------------------------------------------

# Enable or disable the console UI in the terminal.
#
# Options:
#   true   - Enable the console UI.
#   false  - Disable the console UI, use structured log format.
#   iftty  - (Default) Enable UI only if standard out is a TTY.

#console_ui: iftty

# ----------------------------------------------------------------------
# | Console UI Color                                                   |
# ----------------------------------------------------------------------

# Sets the console UI background color in the terminal.
#
# To use a color other than black, set to `transparent` and adjust your
# terminal's background.

#console_ui_color: transparent

# ----------------------------------------------------------------------
# | CRL No Verify                                                      |
# ----------------------------------------------------------------------

# Skip Certificate Revocation List (CRL) verification if set to true.
#
# Accepts a boolean. Default is `false`.

#crl_noverify: false

# ----------------------------------------------------------------------
# | CRL URL                                                            |
# ----------------------------------------------------------------------

# URL to fetch the Certificate Revocation List (CRL) from. Use an
# https:// URL if your network blocks outbound port 80.
#
# Accepts a URL. Default is `http://crl.ngrok-agent.com/ngrok.crl`.

#crl_url: https://crl.ngrok-agent.com/ngrok.crl

# ----------------------------------------------------------------------
# | DNS Resolver IPs                                                   |
# ----------------------------------------------------------------------

# List of DNS servers for resolving tunnel session DNS.
#
# Defaults to using the local system DNS servers.

#dns_resolver_ips:
#  - 1.1.1.1
#  - 8.8.8.8

# ----------------------------------------------------------------------
# | Heartbeat Interval                                                 |
# ----------------------------------------------------------------------

# How often the ngrok agent should heartbeat to the ngrok servers defined
# as a duration.
#
# Accepts a duration (for example, 10s, 1m). The default value is `10s`.

#heartbeat_interval: 1m

# ----------------------------------------------------------------------
# | Heartbeat Tolerance                                                |
# ----------------------------------------------------------------------

# This setting defines the maximum duration to wait for a heartbeat
# response from the server before reconnecting the agent tunnel session.
#
# Accepts a duration (for example, 10s, 1m). The default value is `15s`.

#heartbeat_tolerance: 5s

# ----------------------------------------------------------------------
# | Inspect DB Size                                                    |
# ----------------------------------------------------------------------

# This is the upper limit in bytes on memory to allocate when saving
# requests over HTTP tunnels for inspection and reply.
#
# Accepts a numeric value. The default is `0`, equivalent to 50MB.
#
#   (!) To disable inspection for all tunnels, set the value to `-1`.

#inspect_db_size: 104857600 # 100mb

# ----------------------------------------------------------------------
# | Log Level                                                          |
# ----------------------------------------------------------------------

# Sets the log detail level. Higher verbosity with each level.
#
# Allowed values:
#    crit  - Critical issues.
#    warn  - Warnings.
#   error  - Errors.
#    info  - Informational messages.
#   debug  - Detailed debugging info.

#log_level: info

# ----------------------------------------------------------------------
# | Log Format                                                         |
# ----------------------------------------------------------------------

# Specifies the format of log records.
#
# Allowed values:
#   logfmt  - Human and machine-friendly key/value pairs.
#     json  - Newline-separated JSON objects.
#     term  - Colored format for TTY; otherwise, same as logfmt.

#log_format: json

# ----------------------------------------------------------------------
# | Log                                                                |
# ----------------------------------------------------------------------

# This is the destination where ngrok should write the logs.
#
# Allowed values:
#   stdout  - write to standard out
#   stderr  - write to standard error
#    false  - disable logging
#   <path>  - write log records to file path on disk

#log: /var/log/ngrok.log

# ----------------------------------------------------------------------
# | Metadata                                                           |
# ----------------------------------------------------------------------

# Custom string included in the ngrok API response for identifying tunnels.
#
# Maximum 4096 characters.

#metadata: '{"serial": "00012xa-33rUtz9", "comment": "For customer alan@example.com"}'

# ----------------------------------------------------------------------
# | Proxy URL                                                          |
# ----------------------------------------------------------------------

# URL of an HTTP or SOCKS5 proxy for tunnel connections.
#
#   (!) ngrok will also respect the `http_proxy` and `http_proxy_env`
#       environment variables.

#proxy_url: socks5://localhost:9150

# ----------------------------------------------------------------------
# | Remote Management                                                  |
# ----------------------------------------------------------------------

# Allows remote management of the ngrok agent (stop, restart, update) via
# the ngrok API or Dashboard.
#
# Defaults to `true`.

#remote_management: false

# ----------------------------------------------------------------------
# | Root CAs                                                           |
# ----------------------------------------------------------------------

# Root certificate authorities used to validate TLS connections to the
# ngrok server.
#
# Allowed values:
#    trusted - Use only the trusted certificate root for ngrok.com.
#       host - Use the root certificates trusted by the host's OS (useful for MITM proxies with DPI).
#     <path> - Path to a PEM file with additional trusted certificate authorities.

#root_cas: trusted

# ----------------------------------------------------------------------
# | Server Address                                                     |
# ----------------------------------------------------------------------

# This is the URL of the ngrok server to connect to.
#
#   (!) You should only set this value if you are using a Custom Agent
#       Ingress URL.
#
# https://ngrok.com/docs/agent/connect-url/#custom-connect-url

#server_addr: tunnel.us.ingress.example.com:443

# ----------------------------------------------------------------------
# | Update Channel                                                     |
# ----------------------------------------------------------------------

# Determines the stability of builds for updates.
#
#   (!) Use `stable` for any production deployments.
#
# Allowed values:
#     stable - (Default) Production-ready builds.
#   unstable - Nightly builds; may be unstable. Not for production.
#       beta - Beta builds; may be unstable. Not for production.

#update_channel: stable

# ----------------------------------------------------------------------
# | Update Check                                                       |
# ----------------------------------------------------------------------

# Controls whether the ngrok agent checks for updates.
#
# Defaults to true.

#update_check: false

# ----------------------------------------------------------------------
# | Version  (required)                                                |
# ----------------------------------------------------------------------

# Specifies the version of the config file to use.

version: 2

# ----------------------------------------------------------------------
# | Web Address                                                        |
# ----------------------------------------------------------------------

# Network address to bind for the local agent web interface and API.
#
# https://ngrok.com/docs/agent/web-inspection-interface/
# https://ngrok.com/docs/agent/api/

#web_addr: localhost:4040

# ----------------------------------------------------------------------
# | Web Allow Hosts                                                    |
# ----------------------------------------------------------------------

# List of allowed Host headers for requests to the local agent web
# interface and API. The port is stripped from the Host header before
# matching.
#
# Allowed formats:
#           8.8.8.8  - Matches exact IP in Host header (for example, 8.8.8.8).
#   1:2:3:4:5:6:7:8  - Matches exact IPv6 in Host header.
#        10.0.0.0/8  - Matches any IP within a CIDR range.
#       example.com  - Matches exact hostname.
#      .example.com  - Matches subdomains (for example, sub.example.com).
#
# The default only allows localhost-like Hosts (localhost, 127.0.0.1,
# ::1, and similar).

#web_allow_hosts:
#  - 8.8.8.8
#  - example.com

# ######################################################################
# # Tunnels Configuration                                              #
# ######################################################################

# Define individual tunnels and their configurations.
#
# Each entry under 'tunnels' represents a named tunnel that can be
# started using the 'ngrok start' command:
#   https://ngrok.com/docs/agent/cli/#ngrok-start
#
# To start all tunnels at once, use:
#   ngrok start --all
#
# List of common configuration fields:
#   https://ngrok.com/docs/agent/config/#common-tunnel-configuration-properties
#
# List of HTTP configuration fields:
#   https://ngrok.com/docs/agent/config/#http-configuration
#
# List of TCP configuration fields:
#   https://ngrok.com/docs/agent/config/#tcp-configuration
#
# List of TLS tunnel configuration fields:
#   https://ngrok.com/docs/agent/config/#tls-configuration
#
# List of Labeled tunnel configuration fields:
#   https://ngrok.com/docs/agent/config/#labeled-tunnel-configuration

tunnels:

  # --------------------------------------------------------------------
  # | Basic Tunnel Example                                             |
  # --------------------------------------------------------------------

  # Tunnel configuration for a website protected by basic authentication
  # with a custom host header.
  #
  # Start with after uncommenting:
  #   ngrok start example-website

  # example-website:
  #   addr: 8888
  #   basic_auth:
  #     - "bob:bobpassword"
  #   schemes:
  #     - https
  #   host_header: "app.local"
  #   inspect: false
  #   proto: http
  #   domain: myapp.ngrok.app

  # --------------------------------------------------------------------
  # | End-to-End TLS Tunnel                                            |
  # --------------------------------------------------------------------

  # Tunnel configuration for end-to-end TLS connections.
  #
  # Start with after uncommenting:
  #   ngrok start example-e2e-tls

  # example-e2e-tls:
  #   addr: 9000
  #   proto: tls
  #   domain: myapp.example.com
  #   crt: example.crt
  #   key: example.key

  # --------------------------------------------------------------------
  # | Tunnel with Traffic Policy                                       |
  # --------------------------------------------------------------------

  # Tunnel with a Traffic Policy.
  #
  # Start with after uncommenting:
  #   ngrok start example-traffic-policy
  #
  # More info:
  #   https://ngrok.com/docs/traffic-policy/

  # example-traffic-policy:
  #   traffic_policy:
  #     on_tcp_connect:
  #       - name: LimitIPs
  #         expressions:
  #           - "conn.client_ip != '1.1.1.1'"  # Example rule to deny specific IPs.
  #         actions:
  #           - type: deny
  #   addr: 8000
  #   proto: tcp

  # --------------------------------------------------------------------
  # | SSH Access Tunnel                                                |
  # --------------------------------------------------------------------

  # Tunnel for SSH access.
  #
  # Start with:
  #   ngrok start example-ssh-access

  # example-ssh-access:
  #   addr: 22
  #   proto: tcp
  #   remote_addr: 1.tcp.ngrok.io:12345

  # --------------------------------------------------------------------
  # | Load-Balanced Website Tunnel (Edges)                             |
  # --------------------------------------------------------------------

  # Tunnel with load balancing based on labels.
  #
  # If you uncomment this, you can start this tunnel by running:
  #
  #    ngrok start example-load-balanced-edge

  # example-load-balanced-edge:
  #   labels:
  #     - env=prod
  #     - team=infra
  #   addr: 8000

Tunnel configurations

The most common use of the configuration file is to define tunnel configurations. Defining tunnel configurations is useful because you can then start pre-configured tunnels by name from your command line without remembering all of the right arguments every time. You can also use this method to start as many tunnels as you like from a single ngrok agent. You define tunnels as a mapping of name -> configuration under the tunnels property in your configuration file. Define two tunnels named httpbin and demo:

tunnels:
  httpbin:
    proto: http
    addr: 8000
    domain: alan-httpbin.ngrok.app
  demo:
    proto: http
    addr: 9090
    domain: demo.inconshreveable.com
    inspect: false

Start the tunnel named httpbin:

ngrok start httpbin

Each tunnel you define is a map of configuration option names to values. The name of a configuration option is usually the same as its corresponding command line switch with hyphens (--host-header becomes host_header: in the configuration file and --url becomes url). Tunnels can define a specific proto or use labels to dynamically connect to one or more matching ngrok Edges. All tunnels must define a specific addr that tells the agent where to send the traffic. Other properties are available, and many are protocol-specific. Start all tunnels defined in the configuration file:

ngrok start --all

You can configure a single ngrok agent to tunnel to multiple services within a single agent session.

Common tunnel configuration properties


`addr`	required	forward traffic to this local port number or network address. This can be just a port
`metadata`	Optional	arbitrary user-defined metadata that appears in the ngrok service API when listing tunnel sessions

HTTP configuration


`basic_auth`	Array of `username:password` Strings	This is a list of username:password combinations to use for basic authentication. Passwords must be at least 8 characters long.
`circuit_breaker`	Float	Reject requests when 5XX responses exceed this ratio
`compression`	`true`, `false`	gzip compress HTTP responses from your web service
`host_header`	`rewrite`, `preserve`, custom	Rewrite the HTTP Host header to this value, or `preserve` to leave it unchanged. The `rewrite` option rewrites the host header to match the hostname of the upstream service you are sending traffic to.
`domain`	Any valid domain or hostname that you have previously registered with ngrok.	The domain to request. If using a custom domain, this requires registering in the ngrok dashboard and setting a DNS CNAME value. When creating wildcard endpoints, you need to surround the value with single quotes (domain: ‘*.example.com’).
`inspect`	`true`, `false`	enable/disable the HTTP request inspection in the web and agent API (default: true)
`ip_restriction.allow_cidrs`	Array of CIDRs	Rejects connections that don’t match the given CIDRs
`ip_restriction.deny_cidrs`	Array of CIDRs	Rejects connections that match the given CIDRs and allows all other CIDRs.
`mutual_tls_cas`	Valid system path	The path to the TLS certificate authority to verify client certs in mutual TLS
`oauth.allow_domains`	Array of Strings	Allow only OAuth2 users with these email domains
`oauth.allow_emails`	Array of Strings	Allow only OAuth users with these emails
`oauth.scopes`	Array of Strings	Request these OAuth2 scopes when a user authenticates
`oauth.provider`	String	enforce authentication OAuth2 provider on the endpoint, for example, ‘google’. For a list of available providers, see OAuth2 providers.
`policy.inbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`proto`	`http`	The tunnel protocol name. This defines the type of tunnel you would like to start.
`proxy_proto`	String	The version of PROXY protocol to use with this tunnel, empty if not using. Example values are 1 or 2.
`request_header.add`	Array of `key:value` Strings	The headers to add to the request in the key:value format.
`request_header.remove`	Array of Strings	The header keys to remove from the request.
`response_header.add`	Array of Strings	The headers to add to the response in the key:value format.
`response_header.remove`	Array of Strings	The header keys to remove from the response.
`schemes`	`http`, `https`	Create an HTTP or HTTPS endpoint (or both)
`subdomain`	Any valid combination of letters, numbers, hyphens, or periods.	subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type.
`traffic_policy.on_http_request.name`	String	The name of an `on_http_request` rule that is part of a Traffic Policy
`traffic_policy.on_http_request.expressions`	Array of Strings	Expressions written using CEL that filter traffic the `on_http_request` policy rule applies to
`traffic_policy.on_http_request.actions.type`	String	The type of action that should be executed when this `on_http_request` policy rule is activated
`traffic_policy.on_http_request.actions.config`	custom	The configuration required for the specific type of action specified
`traffic_policy.on_http_response.name`	String	The name of an `on_http_response` rule that is part of a Traffic Policy
`traffic_policy.on_http_response.expressions`	Array of Strings	Expressions written using CEL that filter traffic the `on_http_response` policy rule applies to
`traffic_policy.on_http_response.actions.type`	String	The type of action that should be executed when this `on_http_response` policy rule is activated
`traffic_policy.on_http_response.actions.config`	custom	The configuration required for the specific type of action specified
`user_agent_filter.allow`	Array of Strings	Allows User-Agents that match against these RE2 Regular Expressions
`user_agent_filter.deny`	Array of Strings	Denies User-Agents that match against these RE2 Regular Expressions
`verify_webhook.provider`	String	Verify webhooks are signed by this provider, for example, ‘slack’. For a full list of providers, see Webhook Verification Providers.
`verify_webhook.secret`	String	The secret used by provider to sign webhooks, if there is one
`websocket_tcp_converter`	`true`, `false`	Convert ingress websocket connections to TCP upstream

TCP configuration


`ip_restriction.allow_cidrs`	Array of CIDRs	Rejects connections that don’t match the given CIDRs
`ip_restriction.deny_cidrs`	Array of CIDRs	Rejects connections that match the given CIDRs and allows all other CIDRs.
`policy.inbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`proto`	`tcp`	The tunnel protocol name. This defines the type of tunnel you would like to start.
`proxy_proto`	String	The version of PROXY protocol to use with this tunnel, empty if not using. Example values are 1 or 2.
`remote_addr`	A valid TCP address from ngrok	bind the remote TCP address and port. You can reserve these addresses in the ngrok dashboard to use across sessions. For example: `remote_addr: 2.tcp.ngrok.io:21746`
`traffic_policy.inbound.name`	String	The name of an inbound rule that is part of a Traffic Policy
`traffic_policy.inbound.expressions`	Array of Strings	Expressions written using CEL that filter traffic the inbound policy rule applies to
`traffic_policy.inbound.actions.type`	String	The type of action that should be executed when this inbound policy rule is activated
`traffic_policy.inbound.actions.config`	custom	The configuration required for the specific type of action specified
`traffic_policy.outbound.name`	String	The name of an outbound rule that is part of a Traffic Policy
`traffic_policy.outbound.expressions`	Array of Strings	Expressions written using CEL that filter traffic the outbound policy rule applies to
`traffic_policy.outbound.actions.type`	String	The type of action that should be executed when this outbound policy rule is activated
`traffic_policy.outbound.actions.config`	custom	The configuration required for the specific type of action specified

TLS configuration


`mutual_tls_cas`	Valid system path	The path to the TLS certificate authority to verify client certs for mutual TLS. You also need to specify `key` and `crt` to enable mutual TLS.
`crt`	Valid system path	PEM TLS certificate at this path to terminate TLS traffic before forwarding locally. Requires `--key` to also be specified.
`domain`	Any valid domain or hostname that you have previously registered with ngrok.	The domain to request. If using a custom domain, this requires registering in the ngrok Dashboard and setting a DNS CNAME value. When creating wildcard endpoints, you need to surround the value with single quotes (domain: ‘*.example.com’).
`ip_restriction.allow_cidrs`	Array of CIDRs	Rejects connections that don’t match the given CIDRs
`ip_restriction.deny_cidrs`	Array of CIDRs	Rejects connections that match the given CIDRs and allows all other CIDRs.
`key`	Valid system path	PEM TLS private key at this path to terminate TLS traffic before forwarding locally. Requires `--crt` to also be specified.
`policy.inbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.inbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.name`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.expressions`	Array of Strings	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.type`	String	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`policy.outbound.actions.config`	custom	`policy` has been renamed to `traffic_policy` in agent version 3.14.0.
`proto`	`tls`	The tunnel protocol name. This defines the type of tunnel you would like to start.
`proxy_proto`	String	The version of PROXY protocol to use with this tunnel, empty if not using. Example values are 1 or 2.
`subdomain`	Any valid combination of letters, numbers, hyphens, or periods.	subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type.
`terminate_at`	`edge`, `agent`, or `upstream`	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.inbound.name`	String	The name of an inbound rule that is part of a Traffic Policy
`traffic_policy.inbound.expressions`	Array of Strings	Expressions written using CEL that filter traffic the inbound policy rule applies to
`traffic_policy.inbound.actions.type`	String	The type of action that should be executed when this inbound policy rule is activated
`traffic_policy.inbound.actions.config`	custom	The configuration required for the specific type of action specified
`traffic_policy.outbound.name`	String	The name of an outbound rule that is part of a Traffic Policy
`traffic_policy.outbound.expressions`	Array of Strings	Expressions written using CEL that filter traffic the outbound policy rule applies to
`traffic_policy.outbound.actions.type`	String	The type of action that should be executed when this outbound policy rule is activated
`traffic_policy.outbound.actions.config`	custom	The configuration required for the specific type of action specified

Labeled tunnel configuration


`crt`	Valid system path	The path to a TLS certificate when doing TLS termination at the agent.
`inspect`	`true`, `false`	enable/disable the HTTP request inspection in the web and agent API (default: true)
`key`	Valid system path	The path to a TLS key when doing TLS termination at the agent.
`labels`	A list of labels (name=value) that can be used to identify a tunnel to an ngrok Edge (specifically a tunnel group backend).	The labels for this tunnel in the format name=value. For example: `edge=edghts_2gYaK9XAVa3ANouaDEPrkeaxkYT`

Define two labeled tunnels:

tunnels:
  my-cool-website:
    labels:
      - env=prod
      - team=infra
    addr: 8000
    inspect: false
  ssh-tunnel:
    labels:
      - hostname=my-hostname
      - service=ssh
      - team=development
    addr: 22

When you use labeled tunnels, the matching edge configures the protocol and domain.

Edges automatically create an edge label, for example: edge=edghts_2gYaK9XAVa3ANouaDEPrkeaxkYT

Agent configuration

The following is a list of options that you can configure at the root of your configuration file to specify the behavior of the agent.

Name	Description
api_key	Specifies the ngrok API key used to connect to the ngrok API. This is only needed when using the `ngrok api` command and shouldn’t be confused with the authtoken.
authtoken	Specifies the authentication token (authtoken) used to connect to the ngrok service.
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.
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
crl_url	Override the URL the agent fetches the Certificate Revocation List from.
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 doesn’t 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’s returned as part of the ngrok API response to the list online sessions resource for all tunnels started by this agent.
proxy_url	URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection.
region (Deprecated)	Choose the region where the ngrok agent connects to host its tunnels.
remote_management	Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`.
root_cas	The root certificate authorities used to validate the TLS connection to the ngrok server.
server_addr	This is the URL of the ngrok server to connect to. You should only set this if you’re using a custom ingress URL.
tunnels	A map of names to tunnel definitions. See V2 agent config tunnel definitions for more details.
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`.
version	Specifies the version of the config file to use.
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 IPs, CIDR ranges, and/or hostname suffixes.

`api_key`

This option specifies the API key used to access the ngrok API through the ngrok api command. This is only needed when using the ngrok API and not the local ngrok agent API (available at localhost:4040/api). You can generate an API Key in the ngrok dashboard and install it using the ngrok config add-api-key command. An ngrok.yml file that specifies an API key:

api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN

`authtoken`

This option specifies the authentication token (sometimes called tunnel credential) used to authenticate this agent when it connects to the ngrok service. After you’ve created an ngrok account, your dashboard displays the authtoken assigned to your account. Your authtoken works on multiple machines if you’re just developing. When you want to deploy many agents on many devices, you can generate a unique authtoken for each device in the ngrok dashboard or via the ngrok api credentials command. An ngrok.yml file that specifies an authtoken:

authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

`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.

`console_ui`

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


`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.


`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 skips verifying with the Certificate Revocation List if set to true. This defaults to false.

`crl_url`

The URL the ngrok agent fetches the Certificate Revocation List (CRL) from. The default is http://crl.ngrok-agent.com/ngrok.crl. The URL must use the http or https scheme. Set this option if your network blocks outbound connections on port 80. For example, https://crl.ngrok-agent.com/ngrok.crl fetches the same CRL over HTTPS on port 443. The agent verifies the CRL’s signature, so you can also serve a mirrored copy from your own host. This option has no effect when crl_noverify is true. Available in ngrok agent version 3.39.7 and later.

`dns_resolver_ips`

Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent uses 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 doesn’t 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 tunnels for inspection and reply. The default is 0, which means 50MB.


positive integers		size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels 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.


`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.


`stdout`		write to standard out
`stderr`		write to standard error
`false`	default	disable logging
other values		write log records to file path on disk

log: /var/log/ngrok.log

`metadata`

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

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 cause ngrok to fail. Like many other networking tools, ngrok also respects the environment variable http_proxy and http_proxy_env if it’s set.

`region`

Deprecated This is the region the ngrok agent connects to. You can only choose one region per agent session. Choosing the region closest to you usually improves latency and performance. By default, the ngrok agent attempts to choose the best region for you.

Region Code	Region Name
`ap`	Asia/Pacific (Singapore)
`au`	Australia (Sydney)
`eu`	Europe (Frankfurt)
`in`	India (Mumbai)
`jp`	Japan (Tokyo)
`sa`	South America (São Paulo)
`us`	United States (Ohio)
`us-cal-1`	United States (California)

`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.

`root_cas`

These are the root certificate authorities used to validate the TLS connection to the ngrok server.


`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

`server_addr`

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

`tunnels`

This is a map of names to tunnel definitions. See tunnel definitions for more details.

`update_channel`

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


`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.

`version`

Specifies the version of the config file to use.

`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`

This is a list of specifiers for which Host headers can make requests against the local agent web interface and API. The agent strips any port off the Host header before matching.

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 such as localhost, 127.0.0.1, or ::1
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 matches Host header exactly (example.com)
.example.com		a hostname with a preceding period Host header suffix (sub.example.com or foo.example.com)

Allow an IP address and a domain as Host headers:

web_allow_hosts:
  - 8.8.8.8
  - example.com

​Full example

​Tunnel configurations

​Common tunnel configuration properties

​HTTP configuration

​TCP configuration

​TLS configuration

​Labeled tunnel configuration

​Agent configuration

​api_key

​authtoken

​connect_interface

​connect_timeout

​console_ui

​console_ui_color

​crl_noverify

​crl_url

​dns_resolver_ips

​heartbeat_interval

​heartbeat_tolerance

​inspect_db_size

​log_level

​log_format

​log

​metadata

​proxy_url

​region

​remote_management

​root_cas

​server_addr

​tunnels

​update_channel

​update_check

​version

​web_addr

​web_allow_hosts

Full example

Tunnel configurations

Common tunnel configuration properties

HTTP configuration

TCP configuration

TLS configuration

Labeled tunnel configuration

Agent configuration

`api_key`

`authtoken`

`connect_interface`

`connect_timeout`

`console_ui`

`console_ui_color`

`crl_noverify`

`crl_url`

`dns_resolver_ips`

`heartbeat_interval`

`heartbeat_tolerance`

`inspect_db_size`

`log_level`

`log_format`

`log`

`metadata`

`proxy_url`

`region`

`remote_management`

`root_cas`

`server_addr`

`tunnels`

`update_channel`

`update_check`

`version`

`web_addr`

`web_allow_hosts`