Mac manual install | AI Agent Security

Deploy the Pathfinder agent to Macs and see your first AI coding session in AI Agent Security.

Prerequisites

You have administrator access to the tenant.
The target Macs run macOS 14 (Sonoma), macOS 15 (Sequoia), or macOS 26 (Tahoe). Each agent release supports the current macOS major version and the two before it, so the oldest version drops off when Apple ships a new one. AI Agent Security supports Windows and macOS endpoints only.
For a fleet, an MDM that can push a configuration profile to those Macs. For a single test Mac, administrator rights and physical access to it.
The Macs can reach your AI Agent Security console URL over HTTPS.

Before the agent can inspect what AI tools send over HTTPS, two things must be in place on each Mac: your tenant's root certificate trusted in the System keychain, and the agent's two system extensions approved. One configuration profile from AI Agent Security does both, pushed by your MDM.

🚧
Important
The agent cannot approve itself on macOS. On Windows the agent installs its own root certificate when none is present. macOS does not allow that: a trust-store change and a system extension approval each require MDM or a person at the keyboard. There is no zero-touch macOS deployment without a configuration profile. Without MDM, someone approves the extensions on every Mac.

Choose your deployment path

Path	Use when	How the agent gets there
EPM Package Manager (recommended)	You run BeyondTrust EPM with the Package Manager on your Macs.	Two moves: push the configuration profile (certificate and extension approvals) through your MDM, then choose computer groups in PM Cloud. The Package Manager installs and enrolls the agent from there. The certificate never travels through the Package Manager.
Your own software distribution	You do not run EPM, and you push software with Jamf, Intune, Iru (formerly Kandji), or Munki.	Push the configuration profile through your MDM, then deploy the pkg with an enrollment post-install script or an enrollment plist. Both go out through your tooling.
Single test Mac	You want a trial or a first look on one machine.	By hand on the one Mac: trust the certificate, install the pkg, approve the two extensions, and run one enroll command.

All three paths end in the same state and meet at Verify HTTPS inspection is live.

Path 1: EPM Package Manager (recommended)

If you already run BeyondTrust EPM, this is the shortest path for the agent: no deployment keys to copy and no enroll command. The Deploy AI Agent Security page in PM Cloud creates the deployment key, and the Package Manager on each Mac installs and enrolls the agent.

The certificate and extension approvals are not part of that. The Package Manager cannot change a Mac's trust store or approve a system extension; only MDM can. So this path is still two moves: push the configuration profile through your MDM (step 2), and deploy the agent from PM Cloud (step 3). Until the profile lands, a Mac enrolls and reports in but inspects nothing.

Prerequisites:

The BeyondTrust Package Manager, version 26.3.1 or later, deployed to the target Macs. The page links to the Package Manager installation page if you still need it.
An MDM that can push a configuration profile to those Macs.
AI Agent Security deployment enabled for your PM Cloud tenant. Contact BeyondTrust if the page below does not appear.
A PM Cloud Administrator account with Settings access.

1. Open the Deploy AI Agent Security page

In PM Cloud, go to Settings > Deploy AI Agent Security.

2. Download and push the configuration profile

Step 2 on the page, Configure MDM enrollment, is the macOS step. Select Download Configuration Profile (macOS) and push the .mobileconfig to the target Macs with your MDM. The mechanics are in Distribute the configuration profile below.

📘
Step 1 on that page is the Windows step
Step 1 downloads a root CA .cer for separate distribution and is marked optional for Windows, where the agent installs the certificate itself. On macOS, skip it. The configuration profile in step 2 already carries and trusts the root CA, so you do not need the .cer as well.

Order is flexible: agents install and enroll before the profile arrives, and inspection stays off on a Mac until it does.

3. Add computer groups and deploy

Select Add computer group, select the groups to receive the agent, and confirm. The panel shows each group's computer count, its Windows and Mac split, and whether the Package Manager is installed. PM Cloud creates a deployment key automatically and hands it to the Package Manager. There is nothing to copy and no install command to run.

Check (PM Cloud): the page tracks the key's expiry. If a group's deployment later reports an expired key, redeploying the group creates a fresh one.

4. Watch the rollout

Each deployed group gets a status card showing installed, install failed, and awaiting install counts. Select a card for per-endpoint detail, including the agent version each Mac reports.

Macs pick the agent up at their next Package Manager check-in, up to about 2 hours by default. The agent enrolls itself on install.

Check (in AI Agent Security): go to Visibility > Endpoints. The Macs appear with a recent last-seen time.

🚧
Important
Deployment does not turn on blocking. Deployed Macs are visible, not governed. Their AI activity is recorded, but nothing is blocked until a policy in the Block or Require Approval posture is attached to them. See Run a first session.

Continue at Verify HTTPS inspection is live.

Path 2: Your own software distribution

Use this path with Jamf Pro, Intune, Iru (formerly Kandji), or Munki. In AI Agent Security, go to Settings > Deployment and select Deploy an agent. The wizard lists four steps down the left, Trust the CA, Create a key, Install and enroll, and Test, with operating system tabs across the top. Select the macOS tab. As you go, you collect three things for your distribution tooling: the configuration profile, the pkg, and an enrollment script with a deployment key already in it.

1. Trust the CA

The first step asks how your tenant's root certificate reaches each Mac. Choose Push it with device management (recommended). On macOS the certificate travels inside the configuration profile you download on the Install and enroll step, so there is nothing to download here. Select Continue.

2. Create a key

Enter a Name, such as mac-pilot. For a rollout, set Usage to Multiple uses, and optionally enter a limit in the Max uses box (leave it blank for unlimited). Choose an Expires after value: the default is 7 days, and the options run from 24 hours to 1 year, or No expiry. Select Create & get command.

You never copy a bare key from a dialog. The wizard puts the key into the enrollment script on the next step.

Check (in AI Agent Security): on the Agent Deployment page, the key appears under the macOS heading of the Deployment keys list, with the status Active.

3. Install and enroll

The Install and enroll step has three parts.

Push the configuration profile with your MDM. Under Your MDM, choose Jamf Pro, Microsoft Intune, Iru (formerly Kandji), or Other, then select Download Configuration Profile (macOS). MDMs accept different file formats, and the choice decides which one you get. Upload it as described in Distribute the configuration profile. This is mandatory on macOS: delivered by MDM, the profile trusts the root CA, approves both system extensions, and configures the transparent proxy, with no action needed on each Mac.

Install the pkg. Select Download macOS pkg (universal) and distribute the package with your software tooling. It is a single universal package (pathfinder-sysext-<version>-darwin-universal.pkg) that runs on both Apple Silicon and Intel Macs, so there is no chip choice to make.

Run enrollment as a post-install script. The pkg takes no install arguments, so enrollment happens one of two ways:

MDM post-install script. Paste the script the wizard shows into your MDM's post-install script field (for Intune, the Program step of the macOS app (PKG)). It has your key and console URL already filled in:

#!/bin/bash
set -e
KEY_FILE="$(mktemp)"
trap 'rm -f "$KEY_FILE"' EXIT
printf '%s' 'YOUR-KEY' > "$KEY_FILE"
/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-setup.sh --key-file "$KEY_FILE" --backend YOUR-CONSOLE-URL

Zero-touch enrollment plist. Write an enrollment property list to /var/lib/pathfinder/enrollment.plist before the pkg runs, and the installer's postinstall enrolls the Mac itself, with no script. The file must be root:wheel, mode 0600, and carry SchemaVersion, BackendUrl, and DeploymentKey. The full contract, schema, self-checks, and log lines are in macOS enrollment plist.

🚧
Important
Keep the #! line, and do not add sudo . The Intune macOS app (PKG) Program step rejects a script that does not start with #!, so paste the block as it is. A post-install script already runs as root, so sudo adds nothing. The key travels in a root-only temporary file (--key-file) rather than on the command line (--key), so it never appears in the process list, where any local user could read it with ps. Because set -e makes a failed enrollment exit with an error, your MDM reports the failure instead of recording a healthy install.

Check (on the Mac):
pathfinder-agent status
This asks the running service first. A healthy result shows Enrolled: yes, an agent ID, and your console URL with Connection: connected, along with the current enforcement mode. Add --json for the full report.
Check (in AI Agent Security): go to Visibility > Endpoints. The Mac appears with a recent last-seen time.

Continue at Verify HTTPS inspection is live.

Path 3: Single test Mac

Use this path for a trial on one machine, with administrator rights and physical access. It needs approvals in System Settings that cannot be scripted.

Go to Settings > Deployment, select Deploy an agent, and select the macOS tab, as in Path 2. The difference is the first step: you choose the hands-on option instead of MDM.

1. Trust the CA

On the Trust the CA step, choose Install it yourself. On Windows the same card reads Let the agent install it, but a Mac cannot trust a certificate on its own. Select Download .cer to download your tenant's root certificate (pathfinder-root-ca.cer), then run the command the step shows in Terminal:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/Downloads/pathfinder-root-ca.cer

Adjust the path if you saved the file somewhere else.

🚧
Important
Run this at the Mac's own console, not over SSH. Writing System keychain trust settings needs an authorization prompt that cannot display in an SSH session. Over SSH the command fails with SecTrustSettingsSetTrustSettings: The authorization was denied since no user interaction was possible. The certificate is still imported, so it looks present but is not trusted. Confirm trust explicitly:
security verify-cert -c ~/Downloads/pathfinder-root-ca.cer -k /Library/Keychains/System.keychain
A working install prints ...certificate verification successful., and an imported but untrusted certificate prints CSSMERR_TP_NOT_TRUSTED.

📘
The .cer alone gives process and file enforcement only, not TLS. Trusting the certificate and approving the extensions (below) is enough for process and file policies, but network and TLS inspection also need the transparent proxy configuration in the configuration profile. Without it the network extension is approved but never runs, so network and TLS inspection policies never evaluate. To get it on a single Mac without MDM, go to Settings > Administration, select the Trust anchor tab, choose Other under Your MDM, and select Download Configuration Profile (macOS). Open the .mobileconfig on the Mac and approve it under System Settings > General > VPN & Device Management. macOS does not allow installing profiles from the command line, so this step happens in System Settings.

2. Create a key

On the Create a key step, enter a Name, leave Usage at One-time use, choose an Expires after value, and select Create & get command. The wizard puts the key into the enroll command on the next step.

3. Install the pkg and approve the extensions

On the Install and enroll step, select Download macOS pkg (universal), open the downloaded pkg, and complete the installer before you continue. The extensions and the setup script exist only once it has run.

macOS then shows two extension approval prompts. Either select Open System Settings on each, or dismiss both and go to System Settings > General > Login Items & Extensions > Extensions. Turn on both:

Endpoint Security Extensions: Pathfinder Enforcement
Network Extensions: Pathfinder Network Filter

In the same Login Items & Extensions screen, also turn on App Background Activity > BeyondTrust Software. Do not assume it is on by default: on a manual install it is commonly left off, and TLS inspection cannot start without it. Two helper services (com.pathfinder.tls-proxy and com.pathfinder.netfilter.signing-oracle) register through it, and both are required. The proxy creates per-host certificates through the signing helper, so allowing only one still leaves inspection off.

Then turn on Pathfinder Enforcement under System Settings > Privacy & Security > Full Disk Access. Without it the Endpoint Security client cannot attach, and process events never arrive.

4. Enroll

Still on the Install and enroll step, run the enroll command the wizard shows in Terminal. It is the setup script from the pkg, with your key already filled in:

sudo /Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-setup.sh --key YOUR-KEY --backend YOUR-CONSOLE-URL

When the agent checks in, the step shows the Mac's hostname followed by enrolled, without a page refresh. Continue to the Test step.

Check (on the Mac): pathfinder-agent status shows Enrolled: yes and Connection: connected.
Check (in AI Agent Security): the Mac appears under Visibility > Endpoints.

Continue at Verify HTTPS inspection is live.

Distribute the configuration profile

Paths 1 and 2 use this section. The profile is a standard .mobileconfig. Upload it as a device (computer) level configuration profile, not a user level one, and scope it to the target Macs.

The same profile comes in two formats, and MDMs differ in which they accept. In the wizard, choose your MDM under Your MDM and the download is the right one:

Option	Description
Jamf Pro	The wizard gives you a Signed profile. Jamf stores a signed profile as it is instead of rewriting it on import.
Microsoft Intune	The wizard gives you a Plain XML profile. The Intune custom template rejects a signed file with "Must be a well formed XML string".
Iru (formerly Kandji)	The wizard gives you a Plain XML profile, the format Iru documents for custom profiles.
Other	The wizard gives you a Plain XML profile.

Go to Computers > Configuration Profiles > Upload, and select the .mobileconfig you downloaded with Jamf Pro chosen.
Check that the level is Computer Level.
Set Scope to the target computers or smart group, and save.

Macs receive it at their next check-in, or immediately with sudo jamf policy.

Check (any Mac): the profile appears under System Settings > General > Device Management, and both extensions show as enabled under Login Items & Extensions without anyone approving them by hand.
Order does not matter. The profile can arrive before or after the agent. The agent checks again automatically and turns inspection on as soon as trust is in place, with no reinstall.

Verify HTTPS inspection is live

pathfinder-agent status covers enrollment and process and file enforcement, but it does not confirm that traffic inspection came up. A Mac with the root CA trusted and both extensions approved can still be inspecting nothing. Check it separately, on an enrolled Mac:

# 1. Master switch. The server-side tenant setting is projected into this file,
#    so this is the effective value. The other checks can all look healthy
#    while this is false, in which case no traffic is inspected.
sudo grep inspection_enabled /etc/pathfinder/agent.toml            # expect: true

# 2. Is the network extension actually RUNNING (a real PID, not "-")?
#    "activated enabled" in systemextensionsctl means installed and approved, NOT running.
sudo launchctl list | grep NetworkExtension.com.pathfinder

# 3. Is the local proxy listening, and did the extension write its certificate bundle?
sudo lsof -nP -iTCP:8443 -sTCP:LISTEN
ls -l "/Library/Application Support/Pathfinder/pathfinder-trust-bundle.pem"

🚧
Important
The tls-intercept-ready marker is not a sufficient check. /var/run/pathfinder/tls-intercept-ready reflects only the certificate chain and signing helper state. It ignores inspection_enabled, so it can exist while inspection is switched off. It is also not removed when the proxy stops, so it can remain from an earlier healthy period. Treat it as one signal, never as confirmation on its own.

An extension with no PID and no certificate bundle almost always means the transparent proxy configuration never arrived: the profile is missing or, on Path 3, was not installed. If instead inspection_enabled is false, the chain may be fine and inspection is switched off for this endpoint. See Troubleshooting.

A plain curl https://example.com that shows the site's real certificate issuer does not mean inspection is broken. A connection is intercepted only when a TLS inspection policy matches the calling process, so ordinary traffic passes through untouched by design.

Run a first session

Coding hooks let AI Agent Security see and govern individual AI tool calls. No per-user step is needed: the installer sets up machine-wide managed hooks for all four supported assistants (Claude Code, Codex, Cursor, and GitHub Copilot), and the agent enforces them for every user on the Mac.

On a Mac where Claude Code is installed and signed in, run a short session:

claude -p "Create a file named pathfinder-test.txt containing the word hello"

The wizard's Test step has the matching command for each assistant, plus a shell smoke test and a broader prompt.

Check: in AI Agent Security, go to Intelligence > AI Sessions. Your session appears with the file-write tool call visible.

🚧
Important
Seeing sessions is not enforcement. At this point AI activity is recorded, not blocked. A Mac with no policies applied allows everything. Blocking takes two steps, and both are required:

Create and publish a policy in the Block posture, or in Require Approval, which blocks matching activity but lets the user clear the block themselves. Audit records matching activity without blocking it.

Attach it to the Macs. Publishing alone applies it to nothing. Go to Visibility > Endpoints, select the endpoint, then select Policies > Attach policy. You can also attach a policy through tags for groups of Macs. Only attached policies sync to an endpoint and take effect.

The Macs are now enrolled, inspecting, and reporting AI activity.

Next step: go to Protection > Policies, select New policy, and attach the policy to your endpoints, as the warning above describes.

To reinstall a provider's hooks or verify capture by hand, see Coding hooks: install and verify. For fleets where MDM must own the hook configuration files, see Coding hooks MDM payloads (macOS).

Troubleshooting

Symptom	Check	Fix
Deploy AI Agent Security page missing in PM Cloud	PM Cloud Settings menu, signed in as Administrator	The feature is not enabled for your PM Cloud tenant yet (contact BeyondTrust), or your account is not an Administrator with Settings access.
EPM group stuck at awaiting install	Package Manager version on the Macs; group membership	Package Manager must be 26.3.1 or later. Otherwise wait out the check-in cycle, up to about 2 hours by default.
EPM group shows install failed Macs	The group card's detail view in PM Cloud	Open the per-endpoint detail for the failure reason. Verify that the Mac can reach the console URL over HTTPS.
Mac missing from the Endpoints list	`pathfinder-agent status` on the Mac	Enrollment failed. Verify that the deployment key is active and not expired, and that the console URL is reachable over HTTPS. On the EPM path, redeploying the group creates a fresh key.
MDM reports the post-install script failed	The script your MDM ran	The script exits with an error when enrollment fails. Check that the key is still active and that the script still starts with `#!/bin/bash`.
Agent installed but no process events at all	System Settings > Privacy & Security > Full Disk Access	Pathfinder Enforcement needs Full Disk Access, or the Endpoint Security client cannot attach. The configuration profile grants it; a Mac installed by hand needs it set manually.
Extensions show as not enabled and nobody can enable them	Whether the profile landed, under System Settings > General > Device Management	The profile has not arrived or is not scoped to this Mac. Scope it again in your MDM. On a managed Mac, the extensions cannot be approved any other way.
Network extension has no PID or no certificate bundle	The checks in Verify HTTPS inspection is live	The transparent proxy configuration never arrived. On Paths 1 and 2, push the configuration profile through MDM. On Path 3, open the `.mobileconfig` again and approve it under System Settings > General > VPN & Device Management.
Zero-touch enrollment did nothing, but the install looked clean	`log show --predicate 'eventMessage CONTAINS "pathfinder-autoenroll"' --last 1h`	The enrollment plist was missing or refused. Each log line names the outcome. See macOS enrollment plist.
A plist delivered again to move a Mac to another backend changed nothing	The same log, for `SKIPPED: host is already enrolled`	This is deliberate: an installer never points an enrolled Mac somewhere else. Unenroll it first.
Sessions appear but nothing is blocked	The endpoint's Policies tab	Usually the policy was published but never attached to this Mac. Attach it, directly or through tags. Also confirm the policy posture is Block or Require Approval; Audit never blocks.
Session not appearing in AI Sessions	The Hook enforcement row on the endpoint's Health tab	If the row reads Degraded, reinstall the machine-wide hooks with `sudo pathfinder-agent hook install --all-providers`, then start a fresh session.

Nothing here breaks user traffic. Until the certificate chain is verified on a Mac, HTTPS passes through encrypted and untouched, and the Mac is not inspected yet.