Configure runners for internal APIs

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.

As a Team Admin or Super Admin, you can use Private API Monitoring to create a runner that monitors and tests your organization’s APIs from your internal network, without publicly exposing your endpoints.

You can start the runner with the Postman CLI command from your internal network and securely poll Postman for monitor runs. Once you set up the runner in your internal network, your teammates can select the runner when creating monitors. You can check the monitor results in Postman to learn about your monitor’s performance.

As a Team Admin on a Postman Enterprise plan, you can also create runners from Runner settings.

Create a runner when you configure a monitor

As a Team Admin, you can create a new runner when you configure a monitor. Runners created this way are visible in all your team’s internal workspaces in your team.

To create a runner when you configure a monitor, do the following:

1. Click Monitors in the sidebar, then create or edit a monitor.

2. Under Runners, select Manually Select then click Add Runner.

   

3. Give your runner a name and description.

4. Click Next: Install Runner.

5. Click Copy to clipboard to copy the Postman CLI runner command with the runner ID and key. Then click Done.

   You can’t access the runner key again later. You can reset the runner key later, if needed.

6. Set up the runner in your internal network.

Create a runner from Runner settings

Runner settings is available with Postman Enterprise plans only. To enable Private API Monitoring in your Enterprise team, contact your Postman Customer Success Manager.

As a Team Admin, you can create a new runner from Runner settings.

To create a runner from Runner settings, do the following:

1. Select Team > Team Settings in the Postman header.

2. Click Runners in the left sidebar.

3. Click Add Runner in the upper right of Runner settings.

   

4. Give your runner a name and description.

5. Choose internal workspaces where the runner is visible. Select one of the following:

   • All internal workspaces in team - The runner is visible in all internal workspaces in your team.

   • Selected workspace - Click the Select workspace dropdown list and then select the internal workspace where the runner is visible.

     You can change this later when you’re ready to make the runner visible in all your team’s internal workspaces.

6. Click Next: Install Runner.

7. Click Copy to clipboard to copy the Postman CLI runner command with the runner ID and key. Then click Done.

   You can’t access the runner key again later. You can reset the runner key later, if needed.

8. Set up the runner in your internal network.

Learn how to manage your runners from Runner settings.

Set up a runner with the Postman CLI

Set up your runner in your internal network using the Postman CLI command with the runner ID and key. 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. You can also containerize the runner using Docker. Once the runner is set up in your internal network, your teammates can select the runner when creating a monitor.

To set up the runner in your internal network, do the following:

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 login command to sign in and authenticate with Postman. Learn more about signing in with the Postman CLI.

   postman login --with-api-key <api-key>
   

3. Run the Postman CLI runner command with the runner ID and key. Learn more about the command.

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

Once you’ve set it up, the runner runs in the background, polling Postman for upcoming monitor runs. 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.

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.

Containerize the runner using Docker

1. Use the following example to create a Dockerfile that installs the Postman CLI using npm and starts the runner. This example installs the latest version of the Postman CLI.

   FROM --platform=linux/amd64 node:20-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 globally
   RUN npm install -g postman-cli
   
   ENV POSTMAN_RUNNER_ID=""
   ENV POSTMAN_RUNNER_KEY=""
   
   # Set working directory for runner
   WORKDIR /app
   
   # Create Postman directories with proper permissions
   
   RUN mkdir -p /.postman/logs && \
       chmod -R 777 /.postman && \
       chmod -R 777 /app
   
   # Run the runner
   CMD ["sh", "-c", "postman runner start --id ${POSTMAN_RUNNER_ID} --key ${POSTMAN_RUNNER_KEY}"]
   

   Learn more about installing the Postman CLI.

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
   

postman runner start

Run this command to start a runner from your internal network that regularly polls Postman for upcoming monitor runs. Provide the runner ID and key from the command you copied when you created the runner. Learn more about setting up the runner in your internal network.

If the runner is running in the background, stop the runner using your system’s process control. You can also press Control+C or Ctrl+C to stop the runner.

Options

Option	Details
--id <runner-id>	Specifies the runner ID.
--key <runner-key>	Specifies the runner key that authenticates your runner with the Postman cloud.

Example

postman runner start --id 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --key 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Select the runner when creating a monitor

When creating a monitor, select a runner to run in your internal network. Runners are only supported in internal workspaces. After you’ve created the monitor with the runner, you can check your monitor’s results in Postman.

To create a monitor that uses an existing runner, do the following

1. Click Monitors in the sidebar, then create or edit a monitor.
2. Under Run this monitor, specify how often Postman runs the selected monitor. This can be as often as every five minutes for a status page, or a basic check once a week on your endpoints.
3. Under Runners, select Manually Select then select a runner.
4. Continue configuring your monitor.
5. Click Create Monitor.

Check your internal API monitor

Your monitor’s results show the health and performance of your internal APIs. For more information about Postman Monitor features, see View monitor results.