Mac Agent

Install the TD Endpoint Agent on macOS

This guide covers installing the agent on a single Mac, either with the TD Endpoint Installer app (recommended) or from the Terminal.

Requirements

• Apple Silicon Mac (arm64), macOS 13 or later for the installer app

• An administrator account on the Mac

• Your activation code from the ThreatDefence portal

• Network requirements mentioned in the portal

---

Method 1 — TD Endpoint Installer app (recommended)

Install

1. Open the DMG (TD_Endpoint_Installer_<version>.dmg).

1. Drag TD Endpoint Installer into the Applications folder.

2. Launch the TD Endpoint Installer from Applications.

3. Paste your activation code into the field.

   
4. Leave Enable automatic updates (recommended) ticked unless this Mac must stay on a pinned agent version (untick to disable the 6-hourly self-update; it can be re-enabled later with sudo /opt/TDAgent/tdcli/tdcli.bin enable-autoupgrade).

5. Click Install Agent and enter your administrator password when macOS prompts ("TD Endpoint Installer wants to make changes").

6. Wait 1–2 minutes while the agent installs.

Grant Full Disk Access to TDES

Near the end of the install, a dialogue appears: "TD Endpoint Agent — Permissions Required".

1. Click Open System Settings — the Full Disk Access page opens.

1. Enable the toggle for the entry named TDES.

• If TDES is not listed yet, wait a few seconds and reopen the page, or add /Library/Application Support/TDAgent/TDES.app with the + button.

This step authorises the agent's security monitor. Without it the agent runs, but endpoint telemetry is not collected.

After installation

Reopen the app at any time. When the agent is installed, it shows "TDAgent Installed" with the agent version, plus:

• Export Logs… — packs /var/log/tdagent/ into <hostname>_tdmacagent.tar.gz at a location you choose (asks for the admin password). Attach this file to support requests.

• Uninstall — removes the agent from the Mac (asks for confirmation and the admin password).

If the installation fails

The app shows "Agent installation failed, please contact support and attach the exported logs" along with the installer output.

1. Click Get Log Files and save <hostname>_tdmacagent.tar.gz.

2. Send the archive to support.

3. Try Again returns to the activation-code screen once the cause is resolved (typical causes: wrong/expired activation code, no network path to the activation server).

---

Method 2 — Terminal (.run installer)

For administrators who prefer the command line:

sudo ./TD_Endpoint_MacOS.run install --activation_code <ACTIVATION_CODE>

• The activation code may be a bare key or host:key form.

• Auto-updates are enabled by default; add --auto_update no to disable.

• The same TDES Full Disk Access prompt appears at the end — enable the TDES toggle as described above.

• Re-running the installer on an existing install performs a snapshot-protected in-place upgrade (automatic rollback on failure).

Uninstall (Terminal)

sudo /opt/TDAgent/tdcli/tdcli.bin uninstall

Auto-updates

Control it via the Enable automatic updates checkbox at install time, or later per machine with:

sudo /opt/TDAgent/tdcli/tdcli.bin disable-autoupgrade
sudo /opt/TDAgent/tdcli/tdcli.bin enable-autoupgrade

---

Verifying the installation

# All agent services registered with launchd:
sudo launchctl list | grep -E 'com.tdagent|com.threatdefence|com.velocidex'

# Agent version (JSON):
sudo /opt/TDAgent/tdcli/tdcli.bin version

Expected services: com.tdagent.tls, com.tdagent.wazuh, com.tdagent.tdcli, com.threatdefence.tdes, com.tdagent.cron, com.velocidex.velociraptor.