Start a runner with the built-in proxy server

Use the following examples to start a runner with Postman’s built-in proxy server. With the built-in proxy server, you can control outbound requests using your own authorization service without deploying or managing your own proxy server.

First, create a runner authorization service API with an endpoint that validates outbound requests using the required JSON formats. Create a runner authorization service with rules that determine which requests from the runner are allowed or blocked. After the authorization service is deployed and running, you can start a runner or containerize a runner using Docker in your cloud network, such as a virtual private cloud.

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:

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

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

1
{
2
  "allowed": true
3
}

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.

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.

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:

   1
   FROM --platform=linux/amd64 node:22-bookworm-slim
   2
   3
   # Install CA certificates for SSL/TLS connections and curl for health checks
   4
   RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
   5
   6
   # Install Postman CLI
   7
   RUN npm install -g postman-cli
   8
   9
   # Set working directory for runner
   10
   WORKDIR /app
   11
   12
   # Create non-root user and set up directories
   13
   # The directory permissions ensure the runner can write logs and cache data
   14
   RUN groupadd --system --gid 1001 postman && \
   15
       useradd --system --uid 1001 --gid postman --home-dir /app postman && \
   16
       mkdir -p /.postman/logs \
   17
               /app/.postman/logs \
   18
               /app/.postman/cli \
   19
               /app/.postman-runner-proxy-ca && \
   20
       chown -R postman:postman /app && \
   21
       chown -R postman:postman /.postman && \
   22
       chmod -R 777 /.postman && \
   23
       chmod -R 777 /app/.postman-runner-proxy-ca
   24
   25
   # Switch to non-root user for security
   26
   USER postman
   27
   28
   # Start the Postman runner with the built-in proxy enabled
   29
   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.

Docker containers can’t use localhost to reach authorization services on your computer. If your authorization service is running on your computer (not in the same Docker container), use the following hosts depending on your platform. Replace 8080 with your authorization service’s port number.

• Mac/Windows: http://host.docker.internal:8080
• Linux: http://172.17.0.1:8080 (The default gateway IP address for a bridge network. Your gateway IP address may vary based on your network’s configuration.)

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