macOS Managed Deployment

Updated: October 9, 2026

Deploy the FireTail Endpoint Agent to your macOS fleet using your organization's MDM software. The agent is distributed as a .pkg and configured through the root user's com.firetail.agent defaults domain.

You will need a FireTail project token, devices enrolled in MDM, and access to your MDM's custom configuration profile, package deployment, and script management features.

Unattended deployment requires a separate CA configuration profile. macOS requires interactive administrator approval when an installer changes certificate trust settings, even when the installer runs as root. Deploy the profile and matching certificate and private key first, then install the agent with certificate generation disabled.

Subscribe to endpoint agent releases via RSS

1. Generate the CA and configuration profile

On an administrator's Mac, download the profile helper script from the macOS release details. The link is read from the profile-helper field in the current release manifest.

You can also download the current helper via CLI:

curl -fsSL "https://assets.cdn.services.firetail.app/releases/endpoint-agent/macos/manifest.json" \
  -o firetail-macos-manifest.json &&
curl -fL "$(plutil -extract profile-helper raw -o - firetail-macos-manifest.json)" \
  -o firetail-profile-helper.sh

Once the download completes, run the helper:

bash ./firetail-profile-helper.sh ./ca

This creates:

  • ca/ca-cert.pem — the CA certificate.
  • ca/ca-key.pem — the matching private key.
  • ca/firetail-ca.mobileconfig — the device configuration profile containing the certificate.

Use a separate CA per customer or fleet. Keep ca-key.pem private and deploy it through a channel intended for secrets; anyone with the key can sign certificates trusted by devices using this CA. Do not include the private key in the agent package. The helper reuses an existing complete certificate and key pair in the output directory.

2. Deploy the configuration profile

Upload ca/firetail-ca.mobileconfig to your MDM as a custom configuration profile and scope it to the device. Assign it to the target devices and wait for the profile to be installed before continuing.

The profile must be pushed through MDM to establish trust without an interactive prompt. Installing it manually by double-clicking the file does not replace this step.

3. Deploy the certificate and private key

Securely transfer ca-cert.pem and ca-key.pem from step 1 to each target device. Place them in /Library/Application Support/com.firetail.agent as root, with the following ownership and permissions:

File Owner Permissions
ca-cert.pem root:wheel 644
ca-key.pem root:wheel 600

For example, run this script as root through your MDM after securely staging the files. Replace /path/to/ca with their staging directory on the target device:

#!/bin/sh
set -eu

CA_SOURCE="/path/to/ca"
DIR="/Library/Application Support/com.firetail.agent"
install -d -o root -g wheel -m 755 "$DIR"
install -o root -g wheel -m 644 "$CA_SOURCE/ca-cert.pem" "$DIR/ca-cert.pem"
install -o root -g wheel -m 600 "$CA_SOURCE/ca-key.pem" "$DIR/ca-key.pem"

Remove staged copies of the private key after deployment. The certificate and key must be the pair used to generate the deployed profile.

On a target device, verify that macOS trusts the deployed certificate:

sudo security verify-cert -c "/Library/Application Support/com.firetail.agent/ca-cert.pem" -p ssl -l -L
echo "exit=$?"

Expect exit=0. A non-zero result means the certificate is missing, invalid, or not trusted; resolve this before installing the agent. A Certificate Transparency warning can appear for a private CA, so use the exit status to determine whether verification succeeded.

4. Configure and install the agent

Download the current macOS .pkg using the download above. Verify its SHA-256 checksum against the macOS release details, then upload it to your MDM:

shasum -a 256 "./<downloaded-file>.pkg"

Replace <downloaded-file>.pkg with the filename you downloaded, including its version. Assign the package only after the profile and certificate files have reached each target device.

Run the following as root through your MDM, replacing YOUR_PROJECT_TOKEN and the package path. If your MDM installs packages separately, run the verification and defaults commands as a prerequisite script and require it to succeed before installation:

#!/bin/sh
set -eu

security verify-cert -c "/Library/Application Support/com.firetail.agent/ca-cert.pem" -p ssl -l -L
defaults write /Library/Preferences/com.firetail.agent install_cert -bool false
defaults write com.firetail.agent project_token -string "YOUR_PROJECT_TOKEN"
installer -pkg "/path/to/<downloaded-file>.pkg" -target /

The system-wide install_cert preference disables certificate generation and interactive trust changes. The installer checks that the existing certificate and key are present, match, are unexpired, and are trusted. Installation fails if those checks do not pass. Keep install_cert set to false for subsequent managed upgrades.

Runtime configuration such as project_token must belong to the root user. The token prefix selects the FireTail SaaS environment and region. The macOS agent runs in proxy mode; see the configuration reference for the proxy port, API port, and debug logging settings.

The installer starts the service. After changing the configuration of an agent that is already monitoring traffic, restart it as root through your MDM:

launchctl kickstart -k system/com.firetail.agent

5. Verify the deployment

Check the agent's status on a target device:

launchctl print system/com.firetail.agent | grep -E '^[[:space:]]*state[[:space:]]*='

Review the agent log for any issues:

sudo tail -n 20 -f /var/log/firetail-agent.log

Interact with a supported AI provider and confirm the activity appears in Employee Logs.

For installation failures, review /var/log/install.log and repeat the certificate trust check from step 3. See Managing the service for commands to stop and start the agent.

Updating the agent

To update the FireTail Endpoint Agent, deploy a newer .pkg through your MDM over the existing installation. Keep the existing CA configuration profile, certificate and private key, and root user's configuration in place. You do not need to uninstall the agent or generate a new CA for a version update.

Download the newer package from the macOS release details, verify its SHA-256 checksum, and upload it to your MDM:

shasum -a 256 "./<downloaded-file>.pkg"

Keep install_cert set to false so the installer verifies the existing CA without generating a replacement or requesting interactive trust approval. For example, run the following as root through your MDM, replacing the package path:

#!/bin/sh
set -eu

security verify-cert -c "/Library/Application Support/com.firetail.agent/ca-cert.pem" -p ssl -l -L
defaults write /Library/Preferences/com.firetail.agent install_cert -bool false
installer -pkg "/path/to/<downloaded-file>.pkg" -target /

If your MDM installs packages separately, run the verification and defaults commands as a prerequisite script and require it to succeed before installing the newer package. The installer also verifies the certificate and matching private key. Resolve any certificate errors before continuing the update.

The existing project token and runtime settings are retained, and the installer restarts the service. Repeat the checks in 5. Verify the deployment after the update.

Uninstallation

Download the uninstaller script from the macOS release details. You can also download the current script via CLI:

curl -fsSL "https://assets.cdn.services.firetail.app/releases/endpoint-agent/macos/manifest.json" \
  -o firetail-macos-manifest.json &&
curl -fL "$(plutil -extract uninstaller raw -o - firetail-macos-manifest.json)" \
  -o firetail-uninstaller.sh

Once the download completes, run the script as root through your MDM:

bash /path/to/firetail-uninstaller.sh

After the agent has been removed, remove the CA configuration profile from those devices through your MDM. The uninstaller removes local files and undoes the agent's proxy settings, but cannot remove trust granted by an MDM profile.