> For the complete documentation index, see [llms.txt](https://docs.threatdefence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.threatdefence.com/endpoint-agent/installation-guides/mac-agent.md).

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

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-3f07621c928a3ab48f3ebddbc7860dc473db9540%2FScreenshot%202026-07-20%20at%202.28.11%E2%80%AFPM.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

2. Drag **TD Endpoint Installer** into the Applications folder.\
   ![](https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-39f2251949c40eb0d46986012ad5eab7c2734bf2%2FScreenshot%202026-07-20%20at%202.27.34%E2%80%AFPM.png?alt=media)
3. Launch the **TD Endpoint Installer** from Applications.
4. Paste your activation code into the field.<br>

   <div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-1cadee97a092d5c0e381fc20676168e663936d4b%2FScreenshot%202026-07-20%20at%202.29.43%E2%80%AFPM.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>
5. 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`).
6. Click **Install Agent** and enter your administrator password when macOS prompts (*"TD Endpoint Installer wants to make changes"*).
7. Wait 1–2 minutes while the agent installs.

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-a6101f1fc9ee17b516fc43dffa8e6a7fb12a926b%2FScreenshot%202026-07-20%20at%202.32.40%E2%80%AFPM.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-f88b4899c35cceeb95b25450ce2d1e3e59849b66%2FScreenshot%202026-07-20%20at%202.52.02%E2%80%AFPM.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-89ca55d3d30132e7610157b82405b909461da3d8%2FScreenshot%202026-07-20%20at%202.52.21%E2%80%AFPM.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

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:

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-16600813cdddcc7a12dc2662a68069db74430bb2%2FScreenshot%202026-07-20%20at%202.34.18%E2%80%AFPM.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

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

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

<div align="left"><figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-8c992ba8196488a95654bd2e5eccc2cb755d8f73%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

* 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)

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

```

<figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2Fgit-blob-f4e6104fa836c4349de3bf8eb2fe756d8390190e%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Auto-updates

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

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

***

### Verifying the installation

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.threatdefence.com/endpoint-agent/installation-guides/mac-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.