Set up a runner in your restricted network

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.

Set up a runner in your internal network to monitor your organization’s internal APIs and send the test results to Postman. To get started, you can learn how to start the runner. Then you can learn how to containerize the runner using Docker when you’re ready to set up the runner in your cloud network, like a virtual private cloud.

How a runner works

Once set up and running in your internal network, the runner works in the background to poll Postman for upcoming monitor runs. Postman recommends installing the Postman CLI and starting the runner on a stable machine in the same internal network as the internal APIs you want to monitor.

When a monitor runs in your internal network, the following happens:

1. The Postman CLI fetches the monitor run configuration with relevant Postman elements, like the associated collection and environment, from the Postman cloud.
2. The collection’s tests run in your internal network.
3. The Postman CLI sends the test results back to the Postman cloud, making them available in the monitor results.

Start a runner

To start a runner, install the Postman CLI and then run the postman runner start command to begin polling Postman for monitor runs.

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 and key.

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

Once you’re ready to set up the runner in your cloud network, learn how to containerize the runner using Docker.

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

Start a runner in your cloud network

To start a runner in your cloud network, such as a virtual private cloud, you can containerize the runner using Docker. Use the following example to create your own Dockerfile that installs the Postman CLI and starts the runner with the postman runner start command. Learn more about the postman runner start command and its supported options to help you configure your Dockerfile.

For extra governance and security, you can configure your runner to use a proxy server that routes traffic and evaluates requests from the runner.

1. Use the following example Dockerfile to install the latest version of the Postman CLI and start the runner without any extra options:

   FROM --platform=linux/amd64 node:22-bookworm-slim
   
   # Install ca-certificates for SSL/TLS connections
   RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
   
   # Install Postman CLI
   RUN npm install -g postman-cli
   
   # Create a non-root user
   RUN groupadd -r postman && useradd -r -g postman -u 1001 postman
   
   # Set working directory for runner
   WORKDIR /app
   
   # Create Postman directories with proper permissions
   RUN mkdir -p /home/postman/.postman/logs && \
       chown -R postman:postman /home/postman/.postman && \
       chown -R postman:postman /app
   
   # Switch to non-root user
   USER postman
   
   # Run the Postman runne
   CMD ["sh", "-c", "postman runner start --id ${POSTMAN_RUNNER_ID} --key ${POSTMAN_RUNNER_KEY}"]
   

   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 and key.

   docker run --rm -e POSTMAN_RUNNER_ID="<runner-id>" -e POSTMAN_RUNNER_KEY="<runner-key>" postman-runner
   

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.