> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade to ngrok Agent v3

> Learn the best way to upgrade from ngrok agent v2 to v3.

<Prompt description="Give this to your AI coding agent to handle the upgrade automatically." actions={["copy", "cursor"]}>
  Help me upgrade my ngrok agent from v2 to v3:

  1. Run `ngrok version` to confirm my current version
  2. Run `ngrok update` to install the latest agent
  3. Run `ngrok config upgrade` to auto-migrate my configuration file to v3 format
  4. Run `ngrok config check` to verify no unrecognized parameters remain
  5. Update any scripts that use single-hyphen flags to double-hyphen (e.g. `-hostname` → `--url`, `-subdomain` → `--url`, `-auth` → `--basic-auth`, `-bind-tls` → `--url`)
  6. Note: HTTP tunnels now only open HTTPS by default — update configs that expect both HTTP and HTTPS endpoints

  Ask to see my `ngrok.yml` and any wrapper scripts before making changes.
</Prompt>

## Upgrading the ngrok Agent to the latest version

Before upgrading, it's beneficial to have the latest version of the ngrok agent installed. If you don't, please [update to the latest version](/agent/cli#ngrok-update) before proceeding.

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. To automatically upgrade, run the following CLI command.

```bash theme={null}
ngrok config upgrade
```

### Unrecognized configuration parameters

Both the previous ngrok agent silently ignored invalid config parameters. 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.

```bash theme={null}
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](#upgrading-the-ngrok-agent-configuration-file).

### 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. In order to setup both an HTTP and an HTTPS endpoint, configure multiple endpoints via the 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](/agent/cli#ngrok-config) 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:
  * `-auth` -> [`--basic-auth`](/agent/cli/#ngrok-http)
  * `-bind-tls` -> [`--url`](/agent/cli/#ngrok-http)
  * `-hostname` -> [`--url`](/agent/cli/#ngrok-http)
  * `-subdomain` -> [`--url subdomain.ngrok-free.dev`](/agent/cli/#ngrok-http)

For a full list of changes to the agent for v3, see the [changelog](/agent/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](/gateway/points-of-presence/).

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

```sh theme={null}
$ 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. ngrok follows the [XDG specification](https://wiki.archlinux.org/title/XDG_Base_Directory) 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:
  * `-auth` -> [`--basic-auth`](/agent/cli/#ngrok-http)
  * `-bind-tls` -> [`--url`](/agent/cli/#ngrok-http)

## 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](/agent/cli/).