Installing Device Agent with Docker

You can install the ThousandEyes Device Agent in a Docker container on a 64-bit Linux distribution with kernel version 5.15 or later. It functions like the Router Agent and can be deployed on desktop computers or servers, managed like any other router. The only difference with Docker Device agent is there is no cross-traffic detection.

System Requirements

• x86 and aarch64/ARM64 CPU architectures, such as Mac M1 are supported.

• Certain performance optimisations require system administrator privileges, so for current versions only "rootful" docker runtimes are supported.

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

Pre-Requisites

1. A client ID and an auth secret (which will be shared separately) is required for installation and must be linked to the appropriate account group in your organization. This directs the Docker agent to the correct account group upon registration. Please contact your account manager to set this up.

2. You need to have Docker installed - as mentioned above, to support all tests this must be able to run containers with root privileges.

Getting Started

Step 1 - Create and Update the Configuration File

1. To begin with, create a folder to store the configuration file. For example,

   mkdir cdev

2. Navigate in the folder using the command:

   cd cdev

3. In this directory, now create the following configuration file:

   nano skagent.cfg

4. Using the following template, add content to the above created file. Make sure to include the client string and auth secret:

   [identity]
   base='docker-arm64'                      # replace with 'docker' for x64
   client='change_me'                             # replace with the client string provided
   mac='change_me'                       # replace with the device's MAC address, obtained with `ifconfig` or `ip link` e.g. e2aa9de46dc0
   
   [metadata.Firmware]
   input='file'
   path='/proc/version'
   
   [authentication]
   secret='change_me'                       # replace with the auth secret provided
   
   [logging]
   level="trace"
   
   [resource_checker.cross-traffic]
   input='/sys/class/net bytes'
   interfaces=['eth0']                      
   
   [updater.cdev_package]
   working_directory='/tmp'

5. Now, save and exit the above configuration file by using contrl-x and then when prompted, press y and press Enter.

Step 2 - Install and Run the Agent

1. While in the cdev directory created above in Step 1, pull the latest image from DockerHub:

   docker pull thousandeyes/device-agent

   a. You can also define a specific version published on Docker Hub. The differences between versions of the agent are documented in the release notes.

   For example, docker pull thousandeyes/device-agent:v7.6.1

2. Start the agent container detached from your terminal (-d).

docker run --name cdev -d --network host -it -v ./skagent.cfg:/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg -v ./logs/:/var/run/opt/samknows/router_agent thousandeyes/device-agent

Alternatively, you can add --rm to run temporarily and delete the container when exiting. For example,

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

Step 3 - Validate the Installation

1. If successfully installed, the agent will start running in the background. You can view the logs to confirm this by running the following command (make sure you are still in cdev folder):

tail –f logs/log

1. You can view the agent in ThousandEyes UI by finding the unit ID and navigating to Connected Devices > Management Suite > Agents. To get the unit ID navigate to cdev/logs/unitid. For example,

cat cdev/logs/unitid

Alternatively, you can run the docker ps –a command to retrieve the container ID and then use the docker logs {container ID} command and find the Unit ID by searching for Unit ID after the Activation response. An example response might be:

[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

In this case, the unit ID is 12606889

You can now find the agent using the unit ID within the ThousandEyes UI. We recommend to save this ID as your account manager may require this for any troubleshooting.

Remove the Agent

You can remove the agent by running the following command :

docker stop cdev

docker rm cdev