> 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/plan-deploy-and-update-the-agent.md).

# Plan, Deploy, and Update the Agent

An agent integration usually follows one of two routes:

* An OEM prepares firmware for reuse.
* An ISP asks its firmware owner (an OEM, device vendor, or in-house team) to support selected devices.

Both routes use the same integration, validation, and release process.

To try the Agent, choose one of these guides: [Embedded Linux Quick Install](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/embedded-linux-quick-install.md), [Docker](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/docker.md), or [Raspberry Pi](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/raspberry-pi.md).

## Before You Start

Confirm with ThousandEyes:

* Who manages the firmware: an OEM or device vendor, or an in-house ISP team.
* The firmware owner's technical contact.
* Who approves field trials, production rollout, and release updates for the ISP.

If an OEM manages the firmware, coordinate with ThousandEyes to ensure the OEM has a ThousandEyes account and agent access before integration begins.

## 1. Scope the Deployment

{% tabs %}
{% tab title="ISP-led" %}
Use this route when an ISP needs an OEM or in-house firmware team to integrate or enable the agent for specific device models.

1. For each target device family, work with your firmware owner to record:
   * Device details:
     * Vendor and exact model or SKU.
     * Deployed count and lifecycle status.
     * Firmware family, release branch (for example, OpenSync), and complete build version.
     * Maximum speed tier.
   * Whether compatible firmware with an agent version that is still supported already exists:
     * Confirm the current agent version with the firmware owner.
     * Find its release date on [Connected Devices Agent Release Versions](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/connected-devices-release-versions).
     * Confirm that the version is within the support period described in the [Device Agent Software Lifecycle Policy](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/lifecycle_policy).
2. Ask the firmware owner to classify each combination:

   | Action           | Meaning                                                                      | Next step                                                          |
   | ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
   | Activate         | A suitable agent-enabled firmware version is already deployed on the device. | Confirm production configuration and include it in the first wave. |
   | Upgrade firmware | A suitable image exists but is not deployed on the ISP's devices.            | Agree how the image will be delivered before activation.           |
   | Integrate        | No compatible agent-enabled image exists for that firmware route.            | Use the applicable production integration guide.                   |
   | Defer            | The combination is not required for the first wave.                          | Record it and return to it later.                                  |
3. Choose the first group of device models on which to deploy the agent.

   It should represent the active install base, important speed tiers, access technologies, and regions.
4. Agree on an initial integration and activation window, such as one to three months, for the first representative production wave.
   {% endtab %}

{% tab title="OEM-led" %}
Use this route when you are an OEM or device vendor integrating firmware for reuse across multiple ISPs.

1. Choose the following:
   * Target device families.
   * Firmware branches to support, such as Generic, OpenSync, or custom.
2. Check the [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md) and identify the applicable [Production Integration Guides](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides.md).

   The same model can have several firmware lines with different kernels, platform APIs, or acceleration support.
   {% endtab %}
   {% endtabs %}

## 2. Choose Who Manages Agent Updates

Use the Agent Updater unless an existing lifecycle-management system or policy requires agent-only delivery.

The Agent Updater receives the approved release instruction, checks that storage is available, downloads and verifies the signed package, installs it, and starts the agent. A failed package download or verification leaves the previous working agent available.

| Update model               | Install       | Responsibility                                                                                                                                                   |
| -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Managed via ThousandEyes   | Agent Updater | ThousandEyes delivers approved agent releases through the Updater. The firmware, package, or container delivery process maintains the Agent Updater integration. |
| Self-managed agent updates | Agent-only    | The firmware owner's release process packages, deploys, restarts, and validates every agent release.                                                             |

See [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md) for storage and memory differences, then use the selected update model throughout the applicable [Production Integration Guides](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides.md).

## 3. Set Up Lab Access

If the firmware owner does not have a ThousandEyes account and agent access, ensure both are in place before integration starts.

ThousandEyes creates or confirms the OEM or firmware owner's account. ThousandEyes also provides the organization's `client` string, development authentication `secret`, and access to the agent package.

## 4. Validate in the Lab

The firmware owner completes the lab [Embedded Linux Quick Install](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/embedded-linux-quick-install.md) on each device, then follows [Validate with Self-Test Mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md) to confirm that the overall self-test summary passes.

* **If measured speeds are lower than expected**, follow [Speed Quick Wins](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-quick-wins.md).

  Use [On-Net Test Server Installation](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/on-net-test-server-installation.md) when you need a controlled baseline to separate device performance from the wider network path.
* **For activation or schedule retrieval failures**, use [Installation and Activation Troubleshooting](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/installation-and-activation-troubleshooting.md).
* **For startup or restart failures**, use [Logs and Service Management](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/logs-and-service-management.md).

Lab validation confirms the integration, but it does not confirm ISP production routing until an agent activates through a confirmed mapping.

## 5. Build or Confirm the Production Integration

The firmware owner builds or confirms the production integration by completing these tasks:

* Follow the applicable [Production Integration Guides](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides.md).
* Choose the identity pattern with [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).
* Consult the [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) for file, program, `dmcli`, `ubus`, and OpenSync inputs.
* Troubleshoot startup and persistence failures with [Logs and Service Management](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/logs-and-service-management.md).

## 6. Confirm Production Routing

Configure production device-to-organization routing after the integration, once the firmware owner can share resolved identity values.

1. Have the firmware owner confirm these details with ThousandEyes:
   * The `client` value for each individual ISP.
   * Whether the `client` value is fixed or resolved dynamically.
   * The reported `base` value only when model-specific routing might be needed.
2. Agree with ThousandEyes on where field-trial and production agents should appear:
   * If the ISP has multiple account groups, the ISP selects the appropriate group.
   * If an OEM deploys to ISPs that are not ThousandEyes customers, their devices register with an internal catch-all organization.
3. If a device uses the `client` string provisioned for a specific organization, ThousandEyes routes it to that organization. Otherwise, ThousandEyes chooses the broadest backend mapping that remains unambiguous. The ISP and OEM do not configure the account group mappings themselves. The mapping uses one or more of these values: the `client`, the `base`, or the detected ASN. See [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).
4. Reboot at least one representative device to confirm that the agent returns with the same Unit ID and resolved configuration.

## Examples

### Routing Examples

**Firmware Identifies the ISP**

Acme, an OEM and device vendor, builds one firmware image for several ISPs. The firmware reads the ISP from its provisioning data and reports `examplenet` as the agent's `client` value.

Once the integration is running, Acme confirms the exact value with ThousandEyes. Because ExampleNet is already a ThousandEyes customer, ThousandEyes maps `examplenet` to ExampleNet's account group.

The `client` value identifies the ISP across every supported Acme model. Acme OEM and ExampleNet validate the mapping by activating a small number of devices and confirming that those devices appear in ExampleNet's account.

**Generic Firmware Cannot Identify the ISP**

Acme, an OEM and device vendor, ships generic retail firmware that cannot identify the ISP. Every device therefore reports `acme-retail` as its `client` value. Devices without an ISP-specific mapping register with an internal ThousandEyes organization. You can migrate them to the appropriate organization later.

ExampleNet later plans to deploy the agent on Acme AX500 devices. Because the firmware still reports `acme-retail`, ThousandEyes confirms ExampleNet's ASN.

If every relevant agent on that ASN should belong to ExampleNet, ThousandEyes can use an ASN mapping. If the mapping must apply only to AX500 devices, ThousandEyes adds the reported `base` value.

Acme validates the integration on representative hardware. ExampleNet then confirms that the field-trial devices appear in its account and report expected results.

### Where Devices Appear

| Device                                             | Destination                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------- |
| Device using the OEM lab configuration             | OEM account                                                         |
| Unclaimed production device using the OEM `client` | Internal catch-all                                                  |
| Device matching an ISP mapping                     | ISP account group                                                   |
| Device reporting an unmapped ISP-specific `client` | Internal catch-all                                                  |
| Existing registered agent                          | Its currently assigned organization until corrected by ThousandEyes |

See [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md) for the complete identity guidance and the current [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) for individual fields.

## 7. Run the ISP Field Trial

Validate the integration on real devices in the field before a wider rollout.

| Owner          | Responsibility                                                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Firmware owner | Confirm installation, startup, and device-level validation.                                                                                     |
| ISP            | Confirm that the ThousandEyes platform shows the agent after a device reboot, the intended agent version, and representative scheduled results. |
| ThousandEyes   | Support investigation of confirmed agent or platform issues.                                                                                    |

Share affected MAC addresses, agent versions, and relevant logs when OEM investigation is needed.

Use [Validate with Self-Test Mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md), [Installation and Activation Troubleshooting](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/installation-and-activation-troubleshooting.md), and [Logs and Service Management](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/logs-and-service-management.md) as needed.

## 8. Plan the Production Rollout and Manage Agent Updates

This section covers rollouts for new integrations and updates to devices that use the Agent Updater.

For agent-only (self-managed) updates, ThousandEyes recommends a similar process when your infrastructure supports it.

### Process Overview

The ISP selects an initial representative canary cohort and reviews it before expanding the rollout.

For new integrations:

1. Before rollout, agree on the rollback owner and mechanism, and ensure that you can pause between cohorts:
   * The ISP owns approval, timing, pausing, and rollback.
   * The firmware owner supports integration failures.
   * ThousandEyes supports agent and platform failures.
2. Continue deferred device and firmware combinations in later iterations.

### Planning the Release

For updates, first review the latest [Connected Devices Agent Release Versions](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/connected-devices-release-versions).

Before scheduling a release, confirm the following with ThousandEyes:

* Target agent version.
* Any customer change policy that affects timing.
* Required notice period, including any policy that specifies how many weeks' notice is required.
* Required approval from an executive, a change advisory board (CAB), or another formal body.
* Change-freeze or blackout windows.
* Exact canary deployment date and time.
* MAC address for every canary device so ThousandEyes can target the update.
* Full rollout date and time.
* Soak period.
* Who can pause the rollout.
* Rollback owner and previous known-good version.

When available, record each Unit ID alongside its MAC address.

### Validating with Canary Devices

Deploy to up to 100 selected devices, or provide ThousandEyes with the selected devices' MAC addresses for Agent Updater updates.

After deployment, reboot at least two devices. In the ThousandEyes platform, confirm the following:

1. All canary devices are visible and online with the new intended agent version.
2. The identity, Unit ID, and configuration remain stable.
3. Allow at least a two-hour soak. A soak longer than 24 hours is recommended to allow a full test configuration cycle. After the soak, confirm that scheduled measurements have resumed and appear representative.

### Managing the Rollout

After the canary devices are confirmed stable, follow a rollout approach similar to Agent Updater-managed updates for new integrations, unless otherwise agreed:

* Stagger the rollout over 24 hours.
* Divide devices into hourly cohorts.
* Distribute devices across each hour.

If issues arise:

* Pause cohorts that have not started if failures exceed the agreed tolerance or show a common unexpected behavior.
* If rollback is required, restore the previous approved agent through the same delivery route. Before restarting the rollout, confirm that the previous version is running and scheduled measurements have resumed.

For Agent Updater-managed updates, ThousandEyes retains the pause and rollback controls described above.
