Installing Device Agent with Docker

You can install the ThousandEyes Device Agent in a Docker container on a 64-bit Linux distribution running kernel version 5.15 or later. The Docker-based agent works like the Router Agent and can be deployed on desktop computers or servers. You can manage it just like any other router.

Cross-traffic detection is not available in the Docker deployment. It will only detect traffic generated by the machine it is installed on.

System Requirements

• CPU Architecture: Supported architectures include x86_64 (Intel/AMD) and aarch64/ARM64 (Apple Silicon, Raspberry Pi)

• Docker Runtime: Only Docker running in rootful mode (as root) is supported. Rootless mode is not supported. Running as root is required for certain performance optimizations.

• Resources: The Device Agent uses 15 MB of disk space. It requires at least 50 MB of RAM for speed tests. For video streaming tests, it may require 250 MB of RAM or more, depending on the service and available bandwidth.

Prerequisites

1. Client ID and Auth Secret: You will need a client ID and auth secret, which must be linked to the appropriate account group in your organization. Contact your account manager to obtain these credentials.

2. Docker Installation: Docker must be installed on the host system.

Getting Started

Step 1: Create the Configuration File

1. Create a directory for the configuration file and navigate into it:

   cd && mkdir cdev && cd cdev

2. Create the configuration file using your preferred text editor:

   nano skagent.cfg

3. Populate the file with the following template, replacing the placeholder values with your credentials:

   [identity]
   base='docker-arm64'       # Use 'docker' for x86_64 (Intel/AMD) or 'docker-arm64' for ARM64 (Apple Silicon, Raspberry Pi)
   client='CHANGE ME'        # Replace with your client ID
   mac='YOUR_MAC_ADDRESS'    # Replace with the device MAC address (e.g., e2:aa:9d:e4:6d:c0)
   
   [metadata.Firmware]
   input='file'
   path='/proc/version'
   
   [authentication]
   secret='YOUR_AUTH_SECRET' # Replace with your auth secret
   
   [resource_checker.cross-traffic]
   input='/sys/class/net bytes'
   interfaces=['eth0']
   
   [updater.cdev_package]
   working_directory='/tmp'

To find the device MAC address, run: ip link show | grep ether

1. Save and exit the file. In nano, press Ctrl+X, then Y, then Enter.

Step 2: Install and Run the Agent

1. Pull the latest image from Docker Hub:

   docker pull thousandeyes/device-agent:latest

   You can also specify a version tag, for example:

   docker pull thousandeyes/device-agent:v7.8.1

   See Docker Hub for available versions.

2. Start the agent container in the foreground to verify the configuration:

   docker run --name cdev --rm --network host -it \
     -v ./skagent.cfg:/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg \
     thousandeyes/device-agent:latest

3. Once confirmed, stop the container (Ctrl+C) and restart it in detached (background) mode:

   docker run --name cdev -d --network host \
     -v ./skagent.cfg:/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg \
     thousandeyes/device-agent:latest

4. To restart the agent after a system reboot:

   docker start cdev

Using Docker Compose (Recommended)

For automatic startup on boot, create a docker-compose.yml file in the cdev directory:

services:
  device-agent:
    image: thousandeyes/device-agent:latest
    container_name: cdev
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./skagent.cfg:/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg

Then start the agent with:

docker compose up -d

Step 3: Validate the Installation

1. Check the agent logs to confirm successful activation:

   docker logs cdev

   Look for the Unit ID in the activation response:

   [2025-11-19 15:32:40.950] [info] [updater] Activation response: {"token":"eyJ0eXAiOiJKV1QiLCJh...
   [2025-11-19 15:32:40.950] [info] [updater] Unit ID: 126068889

   Important: Save the Unit ID—your account manager may need it for troubleshooting.

2. Verify the agent appears in the ThousandEyes UI by navigating to Connected Devices > Management Suite > Agents and searching for the MAC address or Unit ID.

Updating the Agent

The Docker image includes an updater service that automatically retrieves the latest Device Agent version from the ThousandEyes backend. No manual intervention is required—the agent will update itself when new versions are available.

Remove the Agent

To stop and remove the agent:

docker stop cdev
docker rm cdev

If using Docker Compose:

cd ~/cdev && docker compose down