Goodbye tunnels, hello agent endpoints

We are saying goodbye to "tunnels" and hello to "endpoints" in the ngrok agent—a term that’s not only more intuitive but aligns with the industry standard and terminology we already use in the dashboard and API. Tunnels are now called agent endpoints, to reflect that they originate from an agent.

This shift brings changes in the ngrok agent—a new version of the agent configuration file and new flags in the agent CLI. We’ve also unified terminology and configuration across the CLI and agent configuration file to enhance clarity and consistency.

New agent configuration file version

Agent version v3.16.0 introduces version 3 of the agent configuration file. Differences between v2 and v3 are described in the tables below.

To upgrade your v2 configuration file to v3, run the upgrade command:

ngrok config update

Tunnel configurations are still supported in the v3 configuration file format. You can specify both endpoints and tunnels in the same configuration file, with endpoint configurations taking precedence over tunnels. The upgrade command will not modify any configured tunnels nor will it convert any tunnel definitions to endpoint definitions.

After upgrading your v2 configuration file (or creating a new v3 one), remember to run a check to ensure your configuration is correct:

ngrok config check

Creating agent endpoints in the configuration file

Let’s walk through an example of creating an agent endpoint. We want to define an endpoint at the URL restricted.ngrok.dev that receives traffic via HTTPS and forwards incoming requests to localhost on port 9090. We want to only allow requests from a range of IP addresses: 137.100.1.0 to 137.100.1.255.

In the v2 configuration file, we would use the tunnels field with an ip_restriction to create the example endpoint:

version: 2
authtoken: <YOUR_AUTHTOKEN>
tunnels:
  restricted-endpoint:
    proto: http
    domain: restricted.ngrok.dev
    addr: localhost:9090
    metadata: '{ "metadata": { "id": "restricted-endpoint" } }'
    ip_restriction:
      allow_cidrs:
        - "137.100.1.0/24"

This is the v3 configuration:

version: 3
agent:
  authtoken: <YOUR_AUTHTOKEN>
endpoints:
  - name: restricted-endpoint
    url: https://restricted.ngrok.dev
    upstream:
      url: http://localhost:9090
    metadata: '{ "metadata": { "id": "restricted-endpoint" } }'
    description: IP restricted endpoint
    traffic_policy:
      on_http_request:
        - name: "IP restricted policy"
          actions:
            - type: restrict-ips
              config:
                enforce: true
                allow:
                  - "137.100.1.0/24"

In the v3 configuration file, we use the endpoints field. The domain and proto fields are collapsed into a single url field. The addr field is now represented by upstream.url. These changes were made to clarify which value represents the public-facing URL vs. the destination URL.

Additionally, traffic management is now handled with a traffic_policy, allowing for greater flexibility using expressions and actions.

To start the endpoint we just configured, use the following command:

ngrok start restricted-endpoint

See the documentation for a complete list of endpoint configuration options.

Creating agent endpoints in the CLI

To simplify how you specify the endpoint network address, we collapsed the --domain, --scheme, and --remote_addr flags into a new --url flag. Now the network address for all endpoints, whether they are HTTP, TCP or TLS, are configured only using this flag.

We have also added two new flags, --description and --metadata, so you can add custom information to your endpoints.

To make transitioning between the agent configuration file and the CLI as frictionless as possible, we’ve unified our naming conventions across both. This consistency ensures that whether you’re editing configuration files or using CLI commands, the terminology and options remain the same, minimizing confusion and reducing the learning curve.

The table below provides a complete list of flag changes in v3.16.0. Refer to the documentation for a complete list of CLI flags.

Prior to version v3.16.0, you would use the agent CLI to start an endpoint defined by the agent configuration above with the following command:

ngrok http 8080 \
  --scheme https \
  --domain restricted.ngrok.dev \
  --metadata '{ "metadata": { "id": "restricted-endpoint" } }' \
  --traffic-policy-file traffic_policy.yaml

And the following Traffic Policy configuration file:

# traffic_policy.yaml

on_http_request:
  - name: "IP restricted policy"
    actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - "137.100.1.0/24"

With agent versions v3.16.0 and above, you establish connectivity as follows:

ngrok http 8080 \
  --url restricted.ngrok.dev \
  --metadata '{ "metadata": { "id": "restricted-endpoint" } }' \
  --description "IP restricted endpoint" \
  --traffic-policy-file traffic_policy.yaml

Deprecation notice

v2 of the agent configuration file and the --domain, --scheme, and --remote_addr flags in the agent CLI are deprecated as of agent v3.16.0, but they still work and will continue to work for all v3 agents in compliance with our agent version support policy. Support for the v2 configuration file and deprecated CLI flags will be removed in a future release with a major agent version bump to v4.

Give agent endpoints a try now

To start creating agent endpoints from the agent configuration file or the CLI, make sure you’re running v3.16.0 or later of the ngrok agent. If you installed ngrok with a package manager like brew or apt, check those sources for updates. Or, if you installed a binary directly to your PATH, you can also try updating or check out our downloads page.

Of course, you’ll also need to grab a free account to make your agent endpoints accessible through the ngrok network.

p.s. We’d love to hear your feedback and feature requests, for agent endpoints and beyond, in our new ngrok community repository! ❤️