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

{% hint style="info" %}
Cross-traffic detection is not available in the Docker deployment. It will only detect traffic generated by the machine it is installed on.
{% endhint %}

## 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:

   ```bash
   cd && mkdir cdev && cd cdev
   ```
2. Create the configuration file using your preferred text editor:

   ```bash
   nano skagent.cfg
   ```
3. Populate the file with the following template, replacing the placeholder values with your credentials:

   ```toml
   [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'
   ```

{% hint style="info" %}
To find the device MAC address, run: `ip link show | grep ether`
{% endhint %}

4. 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:

   ```bash
   docker pull thousandeyes/device-agent:latest
   ```

   You can also specify a version tag, for example:

   ```bash
   docker pull thousandeyes/device-agent:v7.8.1
   ```

   See [Docker Hub](https://hub.docker.com/r/thousandeyes/device-agent/tags) for available versions.
2. Start the agent container in the foreground to verify the configuration:

   ```bash
   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:

   ```bash
   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:

   ```bash
   docker start cdev
   ```

#### Using Docker Compose (Recommended)

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

```yaml
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:

```bash
docker compose up -d
```

### Step 3: Validate the Installation

1. Check the agent logs to confirm successful activation:

   ```bash
   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](https://app.thousandeyes.com) 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:

```bash
docker stop cdev
docker rm cdev
```

If using Docker Compose:

```bash
cd ~/cdev && docker compose down
```