Skip to main content

Upgrading to ngrok Agent v3

The latest ngrok agent is packed with a ton of new capability but because it is a major release of the agent, there are also some breaking changes to watch out for.

Breaking Changes​

Configuration file - The older configuration file is not compatible with the latest ngrok agent without a few changes. We've automated the process to upgrade so all you need to do is run the new upgrade command.

ngrok config upgrade

Unrecognized configuration parameters - The previous ngrok agent silently ignored any config parameters it didn't understand. This means that you could have a configuration file with parameters that you thought were doing something, but they really weren't. This is also true for the ngrok agent API. The latest ngrok agent will explicitly error when it sees a configuration parameter that it doesn't recognize. It's a good idea to run a check after upgrading to find incompatible arguments.

ngrok config check

This will automatically add version and region options as well as convert the names of legacy options to their new format. If you're only using ngrok with a configuration file, there's nothing else to do. For more information about the changes to the config file, see the following section.

Only HTTPS tunnels by default - ngrok agent HTTP tunnels by default will only open a single HTTPS endpoint for your upstream service instead of both an HTTP and HTTPS endpoint. To enable both, you will need to add --scheme http --scheme https to your ngrok agent command or configuration file.

Automation using the ngrok agent - If you have written any scripts or built wrappers around the ngrok agent using command line flags, there are additional changes you will need to make.

  • Installing the Authtoken is now done with the command ngrok config add-authtoken TOKEN. Check out the ngrok config reference documentation for more information.
  • The ngrok agent only accepts long name flags prefixed with -- and will error if a single hyphen is used. When updating your scripts, ensure flags like --host-header are using double hyphens.
  • The following command flags have changed:

For a full list of changes to the agent for v3, see the changelog.

Changes to choosing a region​

The ngrok agent v3 changes the default region you connect to when opening a tunnel. Instead of choosing the us region, the ngrok agent will attempt to connect to the best region for you, usually the one geographically closest to you. If you run the ngrok config upgrade command, it will automatically add a region: us if your config file was missing it, since that was previously the default. Check out the full list of supported regions.

Upgrading the ngrok Agent Configuration File​

If you configure ngrok to start with a configuration file, the ngrok agent v3 makes it extremely easy to upgrade by providing the ngrok config upgrade command. Running this command will automatically migrate your configuration file to the latest format.

  • It adds a version field which is now required and identifies the configuration version to use. The latest is version: 2
  • It converts configuration parameters that have been renamed, such as bind_tls and auth, to their updated names
$ ngrok config upgrade -h
  NAME:
    upgrade - auto-upgrade configuration file

  USAGE:
    ngrok config upgrade [version] [flags]

  DESCRIPTION:
    Upgrade a configuration file to a version. The default configuration
    file is located at /home/ubuntu/.config/ngrok/ngrok.yml

    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

  OPTIONS:
        --config string       upgrade this config file (default /home/ubuntu/.config/ngrok/ngrok.yml)
        --dry-run             preview the proposed changes
    -h, --help                help for upgrade
        --log string          path to log file, 'stdout', 'stderr' or 'false' (default "false")
        --log-format string   log record format: 'term', 'logfmt', 'json' (default "term")
        --log-level string    logging level: 'debug', 'info', 'warn', 'error', 'crit' (default "info")
        --relocate            relocates the config file to the default location

The ngrok config upgrade command also includes a flag --relocate which will move your configuration file to the updated default location for ngrok agent v3. We follow the XDG specification for storing configuration files.

Once you run that command, you should be ready to go with the latest ngrok agent v3.

Upgrading command line scripts​

The latest version of the ngrok agent includes an updated command line argument parser which introduces a few breaking changes.

  • Installing the authtoken is now done with the command ngrok config add-authtoken TOKEN
  • The ngrok agent only accepts long name flags prefixed with -- and will error if a single hyphen is used. When updating your scripts, ensure things like --hostname and --host-header are using double hyphens.
  • The following command flags have changed:

Next steps​

Now that you've upgraded to the latest configuration file, you're ready to start the latest ngrok agent. There's a lot of new stuff in there, but your old commands should work as well (with the changes from above). Run ngrok -h for help or check out the ngrok agent reference documentation.