> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/docker.md).

# Docker

Use Docker to demonstrate the agent on a PC or integrate it into a supported Linux-based device.

The container includes the Agent Updater.

Docker Desktop on macOS or Windows can demonstrate activation and the portal journey. Because Docker Desktop runs the container in a virtual machine, it cannot validate the target device's network path, cross-traffic detection, or expected performance.

{% hint style="info" %}
When Docker is the production target, see [Plan, deploy and update the Agent](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/plan-deploy-and-update-the-agent.md) before creating the production image.
{% endhint %}

## Before You Start

| Use                | Environment                                                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| PC demonstration   | Docker Desktop on macOS or Windows, or Docker on 64-bit Linux                                                                                         |
| Device integration | Rootful Docker on 64-bit Linux with kernel 5.15 or later                                                                                              |
| Architectures      | `amd64` and `arm64`                                                                                                                                   |
| Memory             | See [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md) |
| Network            | Host networking with working DNS and outbound HTTPS                                                                                                   |

Have the Org Client ID for lab testing or the agreed production label, the corresponding authentication secret, and a stable MAC address ready.

The supported image is `thousandeyes/device-agent`. The `latest` tag is published for `amd64` and `ARM64/v8`. Rootless Docker is not supported.

With host networking on Linux, the agent can monitor traffic counters on the host interface that carries the default route. On Docker Desktop, the agent sees the virtual machine's network interfaces instead of the computer's.

## 1. Create the Configuration

1. On Linux, find the interface carrying the default route:

   ```bash
   ip route show default
   ```

   In the output, the interface name follows `dev`. Replace `eth0` below with that name, then read its MAC address:

   ```bash
   cat /sys/class/net/eth0/address
   ```

   For a Docker Desktop demonstration, use a stable MAC address from the computer's network adapter. Do not use a randomized Wi-Fi MAC address. A stable MAC address identifies the lab agent.
2. Create the configuration directory and file. Replace each `YOUR-...` placeholder before running the command.

   Use `base='docker'` on `x86_64/amd64` and `base='docker-arm64'` on `ARM64/v8`.

   ```bash
   mkdir -p ~/cdev
   cd ~/cdev

   cat > skagent.cfg <<'CONFIG'
   [identity]
   base='YOUR-BASE' # Use `base='docker'` on x86_64/amd64 and `base='docker-arm64'` on ARM64/v8.
   client='YOUR-ORG-CLIENT-ID-OR-PRODUCTION-LABEL'
   mac='YOUR-STABLE-HOST-MAC'

   [metadata.Firmware]
   input='file'
   path='/proc/version'

   [authentication]
   secret='YOUR-AUTHENTICATION-SECRET'

   [resource_checker.cross-traffic]
   input='/sys/class/net bytes'

   [resource_checker.cross-traffic.interfaces]
   input='default route'

   [updater.cdev_package]
   working_directory='/tmp'
   CONFIG

   chmod 600 skagent.cfg
   ```

When you test a production image in the lab, set `client` to your Org Client ID so the agent appears in your organization.

For the final production image:

* **ISP-led integrations** must use their organization's production `client`.
* **OEM-led integrations (multi-ISP firmware)** should use dynamic lookup or an OEM-selected label, as described in [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).
* **OEM-led integrations (single-ISP firmware)** should request and use the ISP organization's production `client`. They can also use the same dynamic lookup or label used for multi-ISP firmware distributions. This approach requires an additional backend mapping coordinated with Cisco.

## 2. Start the Container

1. Pull the current image:

   ```bash
   docker pull thousandeyes/device-agent:latest
   ```
2. Start the container:

   ```bash
   docker run -d --name cdev --rm --network=host \
     --cap-add NET_ADMIN --cap-add NET_RAW \
     -v "$PWD/skagent.cfg:/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg" \
     thousandeyes/device-agent:latest
   ```

   `NET_ADMIN` permits the network and socket tuning needed by measurements, including UDP receive-buffer handling. `NET_RAW` supports tests that need raw network access.

## 3. Confirm Activation

1. Follow the container logs:

   ```bash
   docker logs -f cdev
   ```
2. Wait for the Updater to activate and install the agent.

   Record the Unit ID, then confirm that the agent appears in the expected organization under **Connected Devices > Settings > Agent Settings > Agents**.

## 4. Validate with Self-Test Mode

1. From the directory where the Updater installed the agent, run the agent in self-test mode:

   ```bash
   docker exec -it -w /tmp/installation cdev bin/skagent -K
   docker exec -it -w /tmp/installation cdev bin/skagent --self-test-mode
   ```

   Versions earlier than v7.14 do not support self-test mode.
2. Keep the complete output and Unit ID.

   If a test fails or you encounter an installation or activation issue, use the applicable troubleshooting guide:

   * For self-test failures, follow [Validate with self-test mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md).
   * For installation or activation failures, follow [Installation and activation troubleshooting](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/installation-and-activation-troubleshooting.md).

## 5. Confirm Speed Results Are Satisfactory

Your first self-test speed results should be close to, but slightly below, the theoretical maximum speeds.

By default, self-test mode targets servers outside your network to reflect the home broadband experience. Latency to those servers can reduce throughput.

TCP tests reach about 94% of line rate. On a 1 Gbps line, the theoretical maximum is 940 to 949 Mbps. Added latency might reduce throughput by up to 20%.

{% hint style="info" %}
**Troubleshooting Low Speed Results**

If self-test passes but speed is below the intended tier, use [Speed quick wins](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-quick-wins.md).
{% endhint %}

## Start the Container After a Reboot

For a persistent lab host, use Docker Compose. In `~/cdev`, create `compose.yaml`:

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

Start the container with:

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

## Update the Container

The Agent Updater retrieves approved agent releases but cannot update its container image when its own version changes. To install a newer Updater, pull and recreate the container:

```bash
cd ~/cdev
docker compose pull
docker compose up -d
```

## Remove the Container

If you started the container with `docker run`, stop it:

```bash
docker stop cdev
```

The `--rm` option removes the container after it stops. Your local `skagent.cfg` remains in `~/cdev`.

To remove the Docker Compose container:

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