Reinstall the Endpoint Agent on macOS

To address scenarios that require the agent to be reinstalled, use the reinstallation process to preserve historical data, alert configurations, labels, tests, and proxies. Reinstallation also ensures that you do not consume an additional license.

When you initiate reinstallation, ThousandEyes checks for an existing agent with the same hostname. If an agent is found, the new agent merges with the existing agent and acquires its identity and hostname. If no agent with the same hostname is found, a new agent is created and consumes a new license.

Reinstalling a disabled agent consumes a license if an unused license is available.

Generate the Reinstallation Key

To reinstall an agent, you must have the reinstallation key. This key is unique for every account group.

1. In the ThousandEyes web application, navigate to Endpoint Experience > Agent Settings.

1. Click Regenerate New Key.

2. Save the new reinstallation key locally. The key cannot be retrieved later. To see a key in plain text, regenerate it (which revokes any previous keys).

Reinstall on macOS

Add the following parameters to the --register CLI command:

• reinstallationmethod

• reinstallationkey

Example:

sudo /Applications/ThousandEyes\ Endpoint\ Agent.app/Contents/MacOS/te-agent \
  --register <connection-string> \
  --reinstallationmethod MERGE_BY_HOSTNAME \
  --reinstallationkey "<reinstallation_key>"

MERGE_BY_HOSTNAME is the only valid option to trigger the reinstallation flow.

Error Handling

If the reinstallation key or reinstallation method is invalid during registration, the system returns HTTP 200 with a special status indicating that a token was invalid.

For the connection string, see Installing the Endpoint Agent on macOS.