Agent Endpoints with Traffic Policy Quickstart

Traffic Policy enables you to manage traffic to your ngrok endpoints by dynamically implementing logic based on the request before it reaches your upstream services. This guide will teach you how to configure an Agent Endpoint with a custom Traffic Policy using the ngrok Agent CLI. There are two ways to define your Traffic Policy:

You can create a yaml or json file and manually apply it to specific endpoints when you start them. This approach is best when you want to apply a different Traffic Policy to each endpoint.
You can edit your Agent Configuration File. This file applies to all endpoints you start with the agent CLI by default. Choose this approach to set up traffic management logic for all endpoints running locally on your machine.

This guide will demonstrate both approaches. If you don’t know which to choose, follow the instructions for using a separate policy file.

What you’ll need

An ngrok account.
The ngrok Agent CLI installed.

1. Set up your Traffic Policy

Using a separate policy file
Using the Agent Configuration File

Create a custom Traffic Policy file with the following contents:

on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 200
          body: "Hello, World!"

This policy will respond to each HTTP request with a simple “Hello, World!” message.

Your configuration file version must be set to 3.

Enter the following command into your terminal:

ngrok config edit

In your configuration file, add the following content to the bottom and save the file:

endpoints:
  - name: my-agent-endpoint
    description: My first Agent Endpoint with a Traffic Policy
    upstream:
      url: 80
    traffic_policy:
      on_http_request:
        - actions:
            - type: custom-response
              config:
                status_code: 200
                body: Hello, World!

This policy will respond to each HTTP request with “Hello, World!“

2. Start your endpoint

Using a separate policy file
Using the Agent Configuration File

Run the agent, applying the Traffic Policy you saved in the previous step with the --traffic-policy-file flag:

$ ngrok http 80 --traffic-policy-file policy.yml

This command starts an HTTP tunnel for port 80, using the specified policy.yml Traffic Policy to manage traffic.

Start your Agent Endpoint by running the following command:

ngrok start my-agent-endpoint

This command will start an HTTP tunnel for port 80, using the specified Traffic Policy in the config file to manage traffic.

3. Test it out

After running the ngrok command in the previous step you should now see a URL in the forwarding section. Open the URL in your web browser. You should see the “Hello, World!” message displayed in your browser.

What’s next?

You’ve now successfully set up your first Agent Endpoint with a custom Traffic Policy using the ngrok agent. To learn more about ngrok’s Traffic Policy and its capabilities, check out the following resources:

Learn how the Traffic Policy engine works under the hood.
Check out the example gallery to see Traffic Policy in real-world scenarios.
The list of available actions, macros and variables you can use.

Quickstarts

Actions

Examples

References

Agent Endpoints with Traffic Policy Quickstart

What you’ll need

1. Set up your Traffic Policy

2. Start your endpoint

3. Test it out

What’s next?

Quickstarts

Actions

Examples

References

​What you’ll need

​1. Set up your Traffic Policy

​2. Start your endpoint

​3. Test it out

​What’s next?

What you’ll need

1. Set up your Traffic Policy

2. Start your endpoint

3. Test it out

What’s next?