Set up a runner in your restricted network

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.

Postman identifies a runner using its ID, and a runner uses the ID and key to authenticate with Postman. Any runner started through the Postman CLI using the same ID and key is an instance of that runner. Each instance runs in the background, increasing the number of pollers available to run the monitor. Learn how to scale your runner instances.

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. This creates a new instance of the runner that polls Postman for upcoming 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.

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.

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 runner
   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.

Use datasets with a runner

A monitor that uses a runner can take its test data from a Postman dataset, including data sources that are only reachable from inside your network. The runner reads each data source from the machine it runs on, so that machine needs access to the files and databases the dataset connects to. Learn more about using a dataset with a monitor.

Datasets that have a custom JDBC data source need two more things on the machine where the runner is running:

• A Java runtime — Java 8 or newer, found through the JAVA_HOME environment variable or as java on the PATH. Postman doesn’t bundle Java, and the earlier example Dockerfile doesn’t include it, so add a JRE to your image if your monitors use custom data sources. Run java -version to confirm a runtime is installed. On macOS, /usr/bin/java can exist without a Java runtime behind it, so check the version rather than the path.
• A folder containing the JDBC driver JAR files — Postman doesn’t upload driver files to the cloud, so copy them into your image or mount them into the container.

Pass the driver folder’s path to the --dataset-jdbc-driver-dir option when you start the runner. This option is required to run a dataset that uses a JDBC data source.

postman runner start --id <runner-id> --key <runner-key> --dataset-jdbc-driver-dir /opt/jdbc-drivers

The runner loads drivers only from that folder and matches them by file name, and the driver paths saved in the dataset are ignored. The folder on the runner doesn’t have to match where the driver is stored on the machine that created the dataset.

This file name matching applies to the driver JAR only. The dataset’s actual connection target still has to be reachable from the runner’s machine. For a network database such as MySQL, Postgres, or SQL Server, that means network access to the configured host and port. For a file-based JDBC source such as DuckDB, the dataset stores the database file’s absolute path as a connection variable, so that same path has to exist on the runner’s machine too, with read-write access.