Skip to main content

Overview

The ngrok agent supports an optional YAML configuration file that lets you run multiple tunnels simultaneously and tweak some of its more advanced settings.
YAML is whitespace-sensitive. Use spaces only (tabs are not valid in YAML) and keep keys at the same level aligned to the same column.✅ Valid:
❌ Invalid—upstream is indented inconsistently and will fail to parse:

Default locations

The default location of the ngrok agent’s configuration file varies based on your operating system. The easiest way to find the configuration file location is to run:
which validates and prints the location of the configuration file. For the main operating systems supported, their default file locations are:
  • Linux: ~/.config/ngrok/ngrok.yml, or $XDG_CONFIG_HOME/ngrok/ngrok.yml if XDG_CONFIG_HOME is set
  • macOS (Darwin): ~/Library/Application Support/ngrok/ngrok.yml
  • Windows: "%LocalAppData%\ngrok\ngrok.yml" (%LocalAppData is usually %UserProfile%\AppData\Local.)

Config file merging

The --config flag in the ngrok command lets you specify one or more ngrok configuration files to merge when starting the ngrok agent. The rules for merging are as follows:
  • Values from later configs override those from earlier configs. For example, if config1.yml and config2.yml both set api_key, then calling ngrok http --config config1.yml,config2.yml 80 will use the api_key from config2.yml.
  • Lists are overwritten using the last value.
  • Maps, including the tunnels map, are merged by key and in the case of a duplicate key, the latter value is taken.

Environment variables

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

Configuration file formats