Set up a runner to use a proxy server

Private API Monitoring is available with Postman Basic, Professional, and Enterprise plans. To enable Private API Monitoring in your Enterprise team, contact your Postman Customer Success Manager.

For extra governance and security, you can configure the runner to route HTTP and HTTPS traffic generated during monitor runs through a proxy server that enforces outbound request policies. This is useful for inspecting traffic from the runner and ensuring the runner only communicates with approved destinations.

You can specify an external proxy server URL your organization already uses. Or you can use the built-in proxy server with a runner authorization service you’ve configured to decide which requests from the runner are allowed or blocked. If required by your external proxy server or runner authorization service, you can add custom CA certificates. Learn how to start a runner with the built-in proxy server.

Learn more about the postman runner start command and its supported options.

External proxy server

You can use your organization’s existing external proxy server to route and inspect outbound traffic. Use the --proxy option to specify the external proxy server URL.

postman runner start --proxy <proxy-url> --id <runner-id> --key <runner-key>

Instead of specifying the --proxy option, you can define the proxy server URL using the HTTP_PROXY and HTTPS_PROXY environment variables.

Built-in proxy server

You can use the built-in proxy server to route and inspect outbound traffic using rules defined in your runner authorization service. First, you need to set up a runner authorization service with rules that decide which requests from the runner are allowed or blocked. Learn how to create a runner authorization service and start the runner with the built-in proxy.

Once the authorization service is running, start the runner with the Postman CLI and use the --egress-proxy option to enable the built-in proxy server. Also use the --egress-proxy-authz-url option to specify the URL for the runner authorization service.

postman runner start --egress-proxy --egress-proxy-authz-url <authorization-service-url> --id <runner-id> --key <runner-key>

Instead of specifying the --egress-proxy-authz-url option, you can define the runner authorization service URL using the POSTMAN_RUNNER_AUTHZ_URL environment variable.

When the built-in proxy is enabled, the following happens:

• The runner routes all outbound HTTP and HTTPS traffic through the built-in proxy.
• For each outbound request, the proxy references a runner authorization service that determines if the request is allowed or blocked.
• The proxy only forwards approved requests to their final destination.
• All traffic remains end-to-end encrypted, including HTTPS traffic. The proxy inspects outbound traffic and enforces policies defined by your runner authorization service.

Custom CA certificates

You can specify custom CA certificates if your external proxy server or runner authorization service require them. Use the --ssl-extra-ca-certs option to specify a path to the file in PEM format. Note that the PEM file can have multiple certificates.

postman runner start --ssl-extra-ca-certs <path-to-pem-file> --proxy <proxy-url> --id <runner-id> --key <runner-key>

Start a runner with the built-in proxy server

Use the following examples to start a runner with the built-in proxy server. First create a runner authorization service API with a POST /validate endpoint that validates outbound requests, using the specified JSON request and response format. Create a runner authorization service with rules that decide which requests from the runner are allowed or blocked. Then you can start a runner or containerize a runner using Docker in your cloud network, such as a virtual private cloud.

You can use the Postman CLI to trigger monitor runs for internal APIs within your CI/CD pipeline. Then your team can use your Postman tests to automatically catch regressions and configuration issues during your deployment process. Learn more about running a monitor with the Postman CLI.

Runner authorization service API

Create a runner authorization service API that exposes a POST /validate endpoint. The built-in proxy server calls the endpoint to validate outbound requests from the runner. The runner makes HTTP requests to the runner authorization service based on the URL you specify using the --egress-proxy-authz-url option.

Requests to the runner authorization service must send a JSON payload in the following format:

{
  "url": "https://example.com/api/endpoint?param=value",
  "queryParams": "param1=value1&param2=value2",
  "body": "request body content as string",
  "headers": "{\"content-type\":\"application/json\",\"x-pstmn-outbound-identifier\":\"c9-post\"}",
  "method": "POST"
}

Field	Details
url	(Required) Specify the destination URL.
queryParams	Specify query parameters.
body	Specify request body content.
headers	(Required) Specify the JSON-encoded string with request headers.
method	(Required) Specify the HTTP method (such as, GET, POST, PUT, DELETE).

Responses from the runner authorization service must return a JSON response in the following format:

{
  "allowed": true
}

Field	Details
allowed	(Required) Returns true to allow the request and false to block the request. The runner forwards requests that return 200 OK responses. The runner blocks requests that return any other status code.

Create a runner authorization service

Use the following example code to create and deploy your own runner authorization service in Node.js (v18 or later) with Express. You can implement the runner authorization service using any technology stack and deploy it however you prefer. The only requirement is that the runner authorization service API exposes a POST /validate endpoint using the specified JSON request and response format. Before you start a runner, the runner authorization service must be deployed and running.

1. Use the following JavaScript code example to create your own runner authorization service with rules that decide which requests are allowed or blocked.

   #!/usr/bin/env node
   const express = require("express");
   const app = express();
   app.use(express.json());
   
   const PORT = process.env.AUTH_SERVER_PORT || 8080;
   
   /**
   * Evaluates whether a request from the runner is allowed.
   * Customize with your authorization logic based on: url, method, headers, body, queryParams
   */
   function evaluateRequest({ url, method }) {
   try {
       console.info('Evaluating authorization request');
       const hostname = new URL(url).hostname;
       const pathname = new URL(url).pathname;
   
       // Block unsafe methods
       if (["DELETE", "PUT", "PATCH"].includes(method)) {
       console.warn(`Blocked unsafe method: ${method}`);
       return false;
       }
   
       // Block: Admin paths
       if (pathname.includes("/admin") || pathname.includes("/internal")) {
       console.warn(`Blocked sensitive path: ${method} ${hostname}`);
       return false;
       }
   
       // Add more policies here
   
       // Consider blocking by default in production
       console.info(`Request allowed: ${method} ${hostname}`);
       return true;
   } catch {
       return false;
   }
   }
   
   app.post("/validate", (req, res) => {
   if (!req.body?.url || !req.body?.method) {
       return res.status(400).json({ allowed: false });
   }
   
   const allowed = evaluateRequest(req.body);
   res.status(allowed ? 200 : 403).json({ allowed });
   });
   
   app.listen(PORT, () =>
   console.log(`Runner authorization service on port ${PORT}`)
   );
   

2. Install dependencies for the runner authorization service:

   npm install express
   

3. Run the runner authorization service:

   node <path-to-authorization-service-file>
   

Once the service is running, you can start a runner with the built-in proxy server or containerize a runner using Docker in your cloud network. Use the --egress-proxy-authz-url option to specify the runner authorization service URL, such as http://localhost:8080.

Start a runner

To start a runner, install the Postman CLI and then use the postman runner start command to begin polling Postman for monitor runs. To start the runner with the built-in proxy server, use the --egress-proxy option that enables the built-in proxy server and the --egress-proxy-authz-url option for specifying the URL for the runner authorization service.

You can also learn how to containerize a runner using Docker in your cloud network.

1. Install the Postman CLI. You can run the following command to install the Postman CLI using npm:

   npm install -g postman-cli
   

2. Run the Postman CLI runner command with the runner ID, key, and authorization service URL.

   postman runner start --egress-proxy --egress-proxy-authz-url <authorization-service-url> --id <runner-id> --key <runner-key>
   

   In this example, the value of <authorization-service-url> is the root URL of the authorization service, such as http://localhost:8080.

Start a runner in your cloud network

Use the following example Dockerfile to create your own that installs the Postman CLI and starts the runner with the postman runner start command. The example includes the --egress-proxy option that enables the built-in proxy server and the --egress-proxy-authz-url for specifying the URL for the runner authorization service. This example shows best practices for running the runner in a containerized environment.

You can also learn how to start the runner from your machine with the built-in proxy server.

1. Use the following example Dockerfile to install the latest version of the Postman CLI, start the runner with the built-in proxy server enabled, and specify the runner authorization service URL:

   FROM --platform=linux/amd64 node:22-bookworm-slim
   
   # Install CA certificates for SSL/TLS connections and curl for health checks
   RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
   
   # Install Postman CLI
   RUN npm install -g postman-cli
   
   # Set working directory for runner
   WORKDIR /app
   
   # Create non-root user and set up directories
   # The directory permissions ensure the runner can write logs and cache data
   RUN groupadd --system --gid 1001 postman && \
       useradd --system --uid 1001 --gid postman --home-dir /app postman && \
       mkdir -p /.postman/logs \
               /app/.postman/logs \
               /app/.postman/cli \
               /app/.postman-runner-proxy-ca && \
       chown -R postman:postman /app && \
       chown -R postman:postman /.postman && \
       chmod -R 777 /.postman && \
       chmod -R 777 /app/.postman-runner-proxy-ca
   
   # Switch to non-root user for security
   USER postman
   
   # Start the Postman runner with the built-in proxy enabled
   CMD ["sh", "-c", "postman runner start --id ${POSTMAN_RUNNER_ID} --key ${POSTMAN_RUNNER_KEY} --egress-proxy --egress-proxy-authz-url ${AUTHORIZATION_SERVICE_URL}"]
   

   Learn more about installing the Postman CLI and the postman runner start command to help you configure your Dockerfile.

2. Build an image using your Dockerfile. Tag the image with “postman-runner”.

   docker build -t postman-runner .
   

3. Run the container using the image tagged with “postman-runner”. Provide the runner ID, key, and authorization service URL.

     docker run --rm \
     -e POSTMAN_RUNNER_ID="<runner-id>" \
     -e POSTMAN_RUNNER_KEY="<runner-key>" \
     -e AUTHORIZATION_SERVICE_URL="<authorization-service-url>" \
     postman-runner
   

   In this example, the value of <authorization-service-url> is the root URL of the authorization service, such as http://localhost:8080.

Note: Docker containers can’t use localhost to reach services on your computer. If your authorization service is running on your computer (not in the same Docker container), use:

• Mac/Windows: http://host.docker.internal:8080

• Linux: http://172.17.0.1:8080 (default bridge gateway - may vary based on your network configuration)

  Example:

  docker run --rm \
  -e POSTMAN_RUNNER_ID="<runner-id>" \
  -e POSTMAN_RUNNER_KEY="<runner-key>" \
  -e AUTHORIZATION_SERVICE_URL="http://host.docker.internal:8080" \
  postman-runner
  

  Replace 8080 with your authorization service’s port number.

  For more information and the latest recommended approaches, see Docker’s networking documentation.