Install containerized private minions (CPMs)

Private minions and locations are an add-on feature for paid Synthetics accounts. You may not modify any CPM files and New Relic is not liable for any modifications you make. For more information, contact your account representative or a New Relic technical sales rep.

This document describes the New Relic containerized private minion (CPM), a Docker container based private minion that accepts and executes Synthetics monitors against your private locations.

Private minion enhancements

Because the minion operates as a container instead of a virtual machine, it delivers many features and improvements:

  • Easier to install, start, and update
  • Runs on:
  • Improved security and support for non-root user execution
  • Ability to leverage a Docker container as a sandbox environment
  • Customizable monitor check timeout
  • Custom provided modules for scripted monitor types

System requirements and compatibility

To host CPMs, your system must meet these minimal requirements:

Compatibility for Requirements
Operating system

Linux kernel: 3.10 or higher

MacOS: 10.11 or higher

Windows: Windows 10 64-bit or higher

Processor A modern, multi-core CPU
Memory 2.5 GB of RAM per CPU core (dedicated)
Disk space A minimum of 10 GB per host
Docker version Docker 17.03 or higher
Private location key You must have a private location key

Note on Kubernetes and other container orchestration environments: Because the CPM performs its own orchestration of runner containers for scripted and browser monitor checks, this can result in unexpected behavior in container orchestration environments like Kubernetes. Due to this, the CPM is currently not supported for these environments.

Private location key

Before launching CPMs, you must have a private location key. Your CPM uses the key to authenticate against New Relic Synthetics and run monitors associated with that private location.

If you currently have no private locations, see Create a private location

To find the key for existing private location:

  1. Go to > Private locations.
  2. In the Private locations index, locate the private location you want your CPM to be assigned to.
  3. Note the key associated with the private location with the key key icon.

Sandboxing and Docker dependencies

The CPM runs in Docker and is able to leverage Docker as a sandboxing technology. This ensures complete isolation of the monitor execution, which improves security, reliability, and repeatability. Every time a scripted or browser monitor is executed, the CPM creates a brand new Docker container to run it in called a runner.

The minion container needs to be configured to communicate with the Docker engine in order to spawn additional runner containers. Each spawned container is then dedicated to run a check associated with the Synthetics monitor running on the private location the minion container is associated with.

There are two crucial dependencies required to be provided at launch. To enable sandboxing, ensure your:

  1. Writable and executable directory is mounted at /tmp. The writable directory can be any directory you want the CPM to write into, but New Relic recommends the system's own /tmp to make things easy.

  2. Writable Docker UNIX socket is mounted at /var/run/docker.sock or DOCKER_HOST environment variable. For more information, see Docker's Daemon socket option.

For additional information on sandboxing and running as a root or non-root user, see Security, sandboxing, and running as non-root.

Core count on the host determines how many runner containers the CPM can run concurrently on the host. Since memory requirements are scaled to the expected count of runner containers, we recommend not running multiple CPMs on the same host to avoid resource contention.

Install and update CPM versions

Both installing and updating the CPM are done by pulling the latest Docker image from the repository that the CPM Docker image is hosted on. The command for installing and updating is the same for both cases. Go to for a list of all the releases.

To install a new CPM version or update CPM versions:

  1. Ensure you meet the system requirements.
  2. Stop your container and ensure a CPM instance is not already running.
  3. To override and update any existing CPM versions already on your system, pull the image and run:
      docker pull
  4. If installing, enable the CPM with the copy/paste method.

Be sure to periodically check your docker disk usage to preserve space. See docker's documentation on how to manage docker and how to remove images.

Enable CPM with copy/paste method

To enable with the copy/paste method, Docker service needs to be installed and running. After you've installed the new CPM version, run the following:

  docker run \
    -v /tmp:/tmp:rw \
    -v /var/run/docker.sock:/var/run/docker.sock:rw \

Start the CPM

To start the CPM:

  1. Locate your private location key.
  2. Ensure you've enabled Docker dependencies for sandboxing and installed CPM on your system.
  3. Run the appropriate script for your system. Tailor the common defaults for /tmp and /var/run/docker.sock in the following examples to match your system.

      docker run \
        --name YOUR_CONTAINER_NAME \
        -v /tmp:/tmp:rw \
        -v /var/run/docker.sock:/var/run/docker.sock:rw \
        -p 8080:8080 -p 8180:8180 \
      docker run ^
        --name YOUR_CONTAINER_NAME ^
        -v /tmp:/tmp:rw ^
        -v /var/run/docker.sock:/var/run/docker.sock:rw ^
        -p 8080:8080 -p 8180:8180 ^
  4. Once a message similar to Synthetics Minion is ready and servicing location YOUR_PRIVATE_LOCATION_LABEL appears, your CPM is up and ready to run monitors assigned to that location.

Stop the CPM

You can stop a Docker container either by the container name, or the container ID:

Container name stop

For Linux, MacOS, and Windows:

Container ID stop for Linux/MacOS

In the examples the container is stopped and removed. To only stop the container, omit docker rm $CONTAINER_ID.

  CONTAINER_ID=$(docker ps -aqf name=YOUR_CONTAINER_NAME)
  docker stop $CONTAINER_ID
  docker rm $CONTAINER_ID
Container ID stop for Windows

In the examples the container is stopped and removed. To only stop the container, omit docker rm $CONTAINER_ID.

  FOR /F "tokens=*" %%CID IN ('docker ps -aqf name=YOUR_CONTAINER_NAME') do (SET CONTAINER_ID=%%CID)
  docker stop %CONTAINER_ID%
  docker rm %CONTAINER_ID%

Show help and examples

Running the show help command provides a list of the most commonly used run options directly in the command line interface. Run the following command to show CPM usage examples as well as the list of all the available run options:

  docker run help

To keep track of Docker logs and verify the health of your monitors, see Containerized private minion (CPM) maintenance and monitoring.

Show license information

Running the LICENSE command shows the licensing information for the open source software that we use in the CPM. We love open-source software, and making it easy to view our LICENSE file is one way we show our appreciation to the open source community. Some of these are listed under multiple software licenses, and in that case we have listed the license we've chosen to use. Our license information is also available here: New Relic Synthetics licenses.

docker run LICENSE

CPM version 2.2.27 and up.

Configure CPM

You can configure the containerized private minion with custom npm modules, preserve data between launches, use environment variables, and more. For more information, see CPM configuration.


The CPM and its runner containers will inherit network settings from the host as documented by Docker. For each runner container launched by the CPM, a new bridge network is created. This means docker run command options for networking like --network and --dns passed to the CPM container at launch are not inherited or used by the runner containers.

When these networks are created, they pull from the default IP address pool configured for the docker daemon.

Typically, the runner network is removed after the check is completed. However, if a CPM exits while a check is still running, or exits in another unexpected circumstance, it is possible for these networks to get orphaned. This can potentially use up IP address space that is available to the Docker daemon. If this happens, you may observe INTERNAL ENGINE ERROR code: 31 entries in your CPM logging when trying to create a new runner container. Run docker network prune to clean these up.

Security, sandboxing, and running as non-root

By default, the software running inside a CPM is executed with root user privileges, which is suitable for most scenarios, as the execution is sandboxed.

For more information, see Docker's official documentation about security and AppArmor security profiles.

To change the default AppArmor profile used by containers that CPM spawns to run monitors, see the environment variable MINION_DOCKER_RUNNER_APPARMOR.

To run the CPM as a non-root user, additional steps are required:

Run as non-root user

If your environment requires you to run the CPM as a non-root user, this can be achieved if a couple of conditions are fulfilled.

In the following scenario, the non-root user is my_user.

  1. my_user must be able to use the Docker engine on the host. This can be done by ensuring my_user belongs to the "docker" system group (see related doc) OR by enabling the Docker TCP socket option and passing the DOCKER_HOST environment variable to CPM
  2. my_user must have read/write permission to all the directory/volumes passed to CPM. chmod is the command to tweak these permissions.
  3. Obtain the uid of my_user ​for use in the run command: id -u my_user

Once the conditions are met, use the option "-u <uid>:<gid>" when launching CPM:

  docker run ... -u 1002 ...


  docker run ... -u 1002 -e DOCKER_HOST=http://localhost:2375 ...

Docker image repository

The CPM Docker image is hosted on To make sure your Docker image is up-to-date, see the newrelic/synthetics-minion repository.

Additional considerations for CPM connection

Connection Description
CPMs without Internet access A CPM can operate without access to the internet, but with some exceptions. The CPM needs to be able to contact the "" domain. This is necessary for it to report data to New Relic Synthetics and to receive monitors to execute. Ask your network administration if this is a problem and how to set up exceptions.
Communicate with Synthetics via a proxy To set up communication with New Relic Synthetics by proxy, use the environment variables named MINION_API_PROXY*
Arguments passed at launch Arguments passed to the CPM container at launch do not get passed on to the containers spawned by the CPM. Docker has no concept of "inheritance" or a "hierarchy" of containers, and we don't copy the configuration that is passed from CPM to the monitor-running containers. The only shared configuration between them is the one set at the Docker daemon level.

For more help

Recommendations for learning more: