*** title: Start a runner with the built-in proxy server updated: 2026-02-03T00:00:00.000Z slug: docs/monitoring-your-api/runners/proxy-server/use-built-in-proxy-server max-toc-depth: 2 plan: beta ---------- Private API Monitoring is available with [Postman Basic, Professional, and Enterprise plans](https://www.postman.com/pricing/). To enable Private API Monitoring in your Enterprise team, contact your Postman Customer Success Manager. {/* Dockerfile is correct spelling */} {/* vale Vale.Spelling = NO */} Use the following examples to start a runner with Postman’s [built-in proxy server](/docs/monitoring-your-api/runners/proxy-server/runners-proxy-server/#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](#runner-authorization-service-api) with an endpoint that validates outbound requests using the required JSON formats. [Create a runner authorization service](#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](#start-a-runner) or [containerize a runner using Docker](#start-a-runner-in-your-cloud-network) 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](/docs/postman-cli/postman-cli-run-monitor/). {/* "postman-runner" refers to the Docker image tag name */} {/* vale postman-style-guide.BrandedTerm = NO */} ## 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: ```json wordWrap { "url": "https://example.com/api/endpoint?param=value", "queryParams": "param1=value1¶m2=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: ```json { "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](https://nodejs.org/en/about) (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. ```bash wordWrap #!/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: ```bash npm install express ``` 3. Run the runner authorization service: ```bash node ``` Once the service is running, you can [start a runner](#start-a-runner) with the built-in proxy server or [containerize a runner using Docker](#start-a-runner-in-your-cloud-network) 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](/docs/monitoring-your-api/runners/proxy-server/runners-proxy-server/#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](#create-a-runner-authorization-service). You can also learn how to [containerize a runner using Docker](#start-a-runner-in-your-cloud-network) in your cloud network. 1. [Install the Postman CLI](/docs/postman-cli/postman-cli-installation/). You can run the following command to install the Postman CLI using npm: ```bash npm install -g postman-cli ``` 2. Run the Postman CLI `runner` command with the runner ID, key, and authorization service URL. ```bash postman runner start --egress-proxy --egress-proxy-authz-url --id --key ``` In this example, the value of `` 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](/docs/monitoring-your-api/runners/proxy-server/runners-proxy-server/#built-in-proxy-server) and the `--egress-proxy-authz-url` for specifying the URL for the [runner authorization service](#create-a-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](#start-a-runner) 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: ```dockerfile wordWrap 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](/docs/postman-cli/postman-cli-installation/) and the [`postman runner start` command](/docs/postman-cli/postman-cli-options/#postman-runner-start) to help you configure your Dockerfile. 2. Build an image using your Dockerfile. Tag the image with "postman-runner". ```bash docker build -t postman-runner . ``` 3. Run the container using the image tagged with “postman-runner”. Provide the runner ID, key, and [authorization service](#create-a-runner-authorization-service) URL. ```bash docker run --rm \ -e POSTMAN_RUNNER_ID="" \ -e POSTMAN_RUNNER_KEY="" \ -e AUTHORIZATION_SERVICE_URL="" \ postman-runner ``` In this example, the value of `` 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](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/#how-do-i-connect-from-a-container-to-a-service-on-the-host). {/* vale Vale.Spelling = YES */} {/* vale postman-style-guide.BrandedTerm = YES */}