New: Agent endpoints for enhanced developer experience plus control and governance

Endpoints are a familiar concept in networking, and ngrok users are no strangers to them. As you know, ngrok lets you bring your endpoints online in one line from the agent using the tunnels configuration. Now, with our latest release, you can create agent endpoints – also known as ephemeral endpoints – with enhanced capabilities through our new endpoints configuration. 

This update provides you with deeper insights into your endpoints. You can now find out who initiated an endpoint or a set of endpoints from the agent, identify which traffic policies were applied, and access even more details via the API. This added visibility ensures greater control and governance for NetOps and DevOps teams, empowering them to monitor, manage, and audit network activity more effectively – all while maintaining the simplicity that ngrok is known for.

Endpoint agents with ease of use and DevOps-level control

The version 3 agent configuration file introduces a new root-level key called endpoints. The agent key is now required at the root level, and agent-specific fields are nested underneath.

version: 3
agent:
  authtoken: {Your Authtoken}
endpoints:
  - name: my-endpoint
    url: example.ngrok.io
    upstream:
      url: 8080
      protocol: http2
    metadata: my endpoint metadata
    description: my endpoint description
    traffic_policy:
      inbound:
         - actions:
           - type: custom-response
             config:
               status_code: 200
               content: hello friends!
               headers:
                 content-type: text/plain
           name: my traffic policy

This configuration defines a single endpoint, example.ngrok.io, that will receive traffic via HTTPS on port 8080. Requests to this endpoint receive a jovial custom response - “hello friends!” - as specified by the traffic_policy. 

Below is the complete list of supported fields for agent endpoints.

To start the endpoint named my-endpoint, use the following command:

ngrok start my-endpoint

This command will start all endpoints and tunnels:

ngrok start --all

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.

New flags for creating agent endpoints in the CLI

With the release of ngrok agent version 3.16.0, we've introduced several enhancements to streamline your workflow and improve usability. The ngrok agent provides full support for endpoints, making it easier than ever to manage your network configurations. We added the --url flag to simplify how you specify the endpoint network address. Instead of juggling multiple flags, you can now define your endpoint using just this single, intuitive flag. 

To make transitioning between the agent configuration file and the CLI as seamless 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.

Using the agent CLI, you can start the endpoint defined by the agent configuration above with the following command:

ngrok http 8080 --url "https://example.ngrok.io" --upstream-protocol http2 --metadata "my endpoint metadata" --description "my endpoint description" --traffic-policy-file my_traffic_policy.yaml

and following traffic policy configuration file:

# my_traffic_policy.yaml

inbound:
  - actions:
      - type: custom-response
        config:
          content: hello friends!
          headers:
            content-type: text/plain
          status_code: 200
    name: my traffic policy

The v3.15 agent adds five new flags and deprecates four.

Endpoint observability using the ngrok API

Along with the CLI and configuration file changes, we also bring you an updated API. With the introduction of new fields, we've enhanced observability, offering more detailed insights into your agent endpoints. These new fields are designed to provide richer data within API responses, enabling better monitoring, and optimization of your systems.

To access your agent endpoints with the API, start by generating a new API key in the ngrok dashboard. Then use the agent CLI to add your API key and list your endpoints:

ngrok config add-api-key “{Your API Key}"
ngrok api endpoints list

For an agent running the endpoint configuration above, you’ll receive a response similar to below.

{
  "endpoints": [
    {
      "id": "ep_2lIxQOi83drfJG619NsdxLup13P",
      "created_at": "2024-08-28T21:42:54Z",
      "updated_at": "2024-08-28T21:42:54Z",
      "public_url": "https://example.ngrok.io",
      "proto": "https",
      "hostport": "example.ngrok.io:443",
      "type": "ephemeral",
      "metadata": "my endpoint metadata",
      "description": "my endpoint description",
      "domain": {
        "id": "rd_2lIeBU17hG6tFE9KiSKDdxfhXr9",
        "uri": "https://api.ngrok.com/reserved_domains/rd_2lIeBU17hG6tFE9KiSKDdxfhXr9"
      },
      "tunnel": {
        "id": "tn_2lIxQOi83drfJG619NsdxLup13P",
        "uri": "https://api.ngrok.com/tunnels/tn_2lIxQOi83drfJG619NsdxLup13P"
      },
      "upstream_url": "localhost:8080",
      "upstream_proto": "http2",
      "url": "https://example.ngrok.io",
      "principal_id": {
        "id": "usr_2OOb4Hje60HdTB42lsi8bKg5kSL",
        "uri": ""
      },
      "traffic_policy": "{\"inbound\":[{\"name\":\"my traffic policy\",\"actions\":[{\"type\":\"custom-response\",\"config\":{\"content\":\"hello friends!\",\"headers\":{\"content-type\":\"text/plain\"},\"status_code\":200}}]}]}\n",
      "tunnel_session": {
        "id": "ts_2lIxQP8ujHG6Tu9af6dsxy6LpXM",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_2lIxQP8ujHG6Tu9af6dsxy6LpXM"
      }
    }
  ],
  "uri": "https://api.ngrok.com/endpoints",
  "next_page_uri": null
}

The introduction of the principal_id object in our API offers a powerful tool for investigating who initiated an endpoint, particularly when dealing with bot users. The principal_id returns a URI that you can use to simply query the API for additional information on the bot user. This capability is especially valuable when managing automated processes, allowing you to isolate and understand the specific activities of these processes. For ops and security teams, this feature is crucial for auditing activity and ensuring compliance with internal policies.

The traffic_policy field provides a straightforward way to see which policy is applied to a particular endpoint. This visibility allows for quick verification of traffic rules, ensuring that the correct policies are enforced without having to sift through configurations.

Finally, the tunnel_session object allows you to easily query the API for the status of your endpoint connections using the provided URI:

curl https://api.ngrok.com/tunnel_sessions/ts_2lIxQP8ujHG6Tu9af6dsxy6LpXM -H "authorization: Bearer {Your API Key}" -H "ngrok-version: 2"

with the returned response

{
  "agent_version": "3.16.0",
  "credential": {
    "id": "cr_2OObv0NKkYsx7s4DvlImN3GRufP",
    "uri": "https://api.ngrok.com/credentials/cr_2OObv0NKkYsx7s4DvlImN3GRufP"
  },
  "id": "ts_2lIxQP8ujHG6Tu9af6dsxy6LpXM",
  "ip": "195.55.171.137",
  "os": "linux",
  "region": "us-cal-1",
  "started_at": "2024-09-04T16:16:19Z",
  "transport": "ngrok/2",
  "uri": "https://api.ngrok.com/tunnel_sessions/ts_2lIxQP8ujHG6Tu9af6dsxy6LpXM"
}

This efficient access to session details enables richer diagnostics and more effective management of your endpoints.

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 of the ngrok agent with ngrok version. 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 with ngrok update or view our downloads page.

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

At ngrok, simplicity has always been at the heart of everything we do. Our goal is to empower developers and operational teams with powerful networking capabilities that remain easy to use, whether you’re spinning up a single service or applying complex traffic policy rules to your endpoints. 

We’re continuing that tradition with this release, making it effortless to configure, monitor, and secure your agent endpoints – all while providing the control and visibility that NetOps and DevOps teams need. By simplifying the complex, we’re enabling you to focus on what matters most: building and delivering your applications and APIs with confidence.

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