Install the poison0 agent on macOS
Install, roll out, check and remove the poison0 agent on a Mac.
Requirements
| Requirement | Details |
|---|---|
| Processor | Apple M2 or newer, or an Intel Mac with AVX2 (Intel Haswell, 2013, or newer). Apple M1 is not supported. |
| Rights | Administrator rights. The installer runs as root through sudo. |
| Install key | An install key from the console, under Devices → Roll out many devices with a key. |
| AI agents | At least one AI agent from supported agents. |
Install one Mac
Run this command in the Terminal.
curl -fsSL https://poisonzero.com/install.sh | sudo PZ_ENROLL_CODE="<install-key>" sh
The installer checks the program against SHA256SUMS and stops on a mismatch. Then it installs the service and enrolls the Mac. In a terminal, the installer asks whether to send the device name to the console. You answer Yes or No, there is no default. Yes sends the Mac's computer name, No sends no name. With Jamf, Intune and scripts without a terminal it does not ask and sends no name.
To change the defaults, set the environment variables under Reference.
Check the Mac
- Run
launchctl print system/com.poisonzero.daemon. The service should be running. - Run
poison0 doctorin your desktop session. It names what is wrong. - Open the console. The Mac appears under Devices.
poison0 also answers to p0 and pz. If another program already uses one of these names, that alias is skipped.
After the first install, the model downloads in the background. The fixed rules protect at once.
Roll out to many Macs
Use the package with your tenant's profile, or alternatively a Jamf policy script or an Intune shell script. All run as root.
Package and profile (Intune, Jamf)
This is the recommended path and needs no script. You assign two files to the same Macs: the package poisonzero-<version>.pkg and your tenant's profile <slug>-poisonzero-macos.mobileconfig. The package is signed (Developer ID Jon Knoll (RYR9QUYGWV)), notarized by Apple and the same for every customer. The profile holds your tenant's install key and the setting whether the computer name is sent as the device name.
- In the console open Devices, expand Roll out many devices with a key and select Download Intune package. Choose the macOS tab.
- Optional: tick Use the computer name as device name before you download the profile.
- Under 1. Download package, download the package from the link.
- Under 2. Download profile, download the profile with Download.
Steps in Intune:
- Open Apps → macOS → Add, choose Line-of-business app and upload the package.
- Assign the app to a device group under Required.
- Open Devices → macOS → Configuration → Create → New policy. Choose the profile type Templates → Custom and the deployment channel Device channel. Upload the
.mobileconfigfile. - Assign the profile to the same device group.
Steps in Jamf Pro:
- Upload the package under Settings → Computer Management → Packages.
- Under Computers → Policies, create a policy that installs the package (Packages → Install). Choose a trigger, for example Recurring Check-in, and set the scope to your Macs.
- Under Computers → Configuration Profiles → Upload, upload the
.mobileconfigfile. - Set the scope of the profile to the same Macs.
Package and profile belong to the same Macs, in any order. As soon as both are on a Mac, it enrolls with your tenant. If the profile arrives later, a background service detects it and enrolls the Mac then. Without the profile, the Mac does not connect to your tenant. You see whether PoisonZero runs in the console under Devices.
The profile contains an install key that every admin who can read profiles in your MDM can see. The console lists it as Intune macOS profile with the date. It is valid for one year, so revoke it after the rollout.
To remove PoisonZero, run the uninstall under Uninstall. For a package install it also removes the package receipt. Afterwards, take the package and the profile out of the assignment in your MDM. The profile is also available through the Admin API: POST /v1/intune/macos-profile, see Admin API.
Install the agent
Jamf and Intune run the script without a terminal, so pass the key as an environment variable. In Intune, add the script under Devices → macOS → Shell scripts and set Run script as signed-in user to No. Intune stores the script text with the key, so revoke the key in the console after the rollout. Device name: unless you choose one, PoisonZero sends no name and the console shows a placeholder. PZ_DEVICE_NAME_FROM_HOSTNAME=1 in the script below sends the computer name of each Mac (System Settings → General → About → Name, the name Intune lists). Remove the variable to send no name. The alternatives PZ_DEVICE_NAME and PZ_DEVICE_NAMES_CSV are under Reference. The name is set at the first enrollment only. Later runs of the script do not change it, so rename a Mac in the console.
#!/bin/sh PZ_ENROLL_CODE="<install-key>" PZ_DEVICE_NAME_FROM_HOSTNAME=1 sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"
PoisonZero sets up the protection for the AI agents itself after installation, in every user account and for all supported agents. You do not need to do anything.
Intune (macOS)
Alternatively, the console gives you the finished script with your tenant's install key. You type nothing into Intune.
- In the console open Devices, choose Download Intune package and the macOS tab. Expand Other ways and download the script.
- In Intune, add a script under Devices → macOS → Scripts → Add and upload the file.
- Set Run script as signed-in user to No so that it runs as root. Leave the frequency at Not configured and enter, for example, 3 for Max number of times to retry if script fails.
- Assign the script to a device group.
Requirements: macOS 12 or later, the Mac is enrolled in Intune and reaches the internet without a proxy. Intune installs the Intune agent itself once a script is assigned to the Mac. The agent fetches new scripts about every 8 hours. In Company Portal, Check settings speeds that up.
The script does not enroll a Mac that is already enrolled a second time. Intune shows only success or failure per Mac. Whether PoisonZero is running, you see in the console under Devices.
The script contains an install key that every Intune admin with read access to scripts can see. The console lists it as Intune macOS with the date. It is valid for one year; revoke it after the rollout.
Private Macs: signed configuration
A private Mac takes no settings from the cloud. It reads a signed client-config.json.
- In the console, open the profile and select Export for private devices.
- Pass the file to the installer with
PZ_CONFIG, as shown below. - Or place it with the Jamf script that the console shows after the export.
curl -fsSL https://poisonzero.com/install.sh | sudo \ PZ_ENROLL_CODE="<install-key>" PZ_CONFIG="./client-config.json" sh
The installer checks the file with poison0 config verify and places it in /Library/Application Support/PoisonZero/client-config.json, readable by root only.
Update
Cloud devices update themselves. To turn this off per device, use Settings → Protection & Devices → Updates in the console. Private devices do not update themselves.
To update by hand, run the install command again. It keeps the credentials. More in updates and lifecycle.
From this version, the program file is /usr/local/bin/poison0. poisonzero links to it and keeps working, and folder exclusions stay valid. For file or process exclusions, add poison0 and keep poisonzero, because agent hooks still call it.
Uninstall
curl -fsSL https://poisonzero.com/install.sh | sudo sh -s -- --uninstall
The uninstall first removes the agent hooks of every user and stops if that fails. Then it removes the service, the notifier, the commands, the program and the data directory.
For a Homebrew install, remove the hooks first:
poison0 remove-agent-integration && brew uninstall poisonzero
Open quarantine cases
The uninstall lists each open quarantine case with its original path, the quarantined copy (*.infection.pz) and how to restore it. A copy stays in /Library/Application Support/PoisonZero-quarantine, readable by root only.
Set PZ_UNINSTALL_SKIP_QUARANTINE_COPY=1 to skip that copy. Nothing is restored automatically. Check each file before you restore it.
The uninstall drops held changes that still wait for review. To keep one, approve it first: list them with poison0 quarantine pending, then run poison0 quarantine pending approve <id>.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
poison0 doctor shows that the model download failed. | The background download after the first install did not finish. | Run sudo poison0 model to retry now. poison0 doctor shows the reason. |
poison0 exec0 status shows that Claude Code does not call the exec0 hook. | Claude Code settings come from an MDM profile (domain com.anthropic.claudecode) or the claude.ai admin console. Claude Code then ignores 50-poisonzero-exec0.json. | Set "managedSourcesBehavior": "merge" in that source (Claude Code 2.1.242 or later), or copy the content of the file into it. |
poison0 doctor reports that the managed hooks are off. | Claude Code's managed settings set "disableAllHooks": true. This also turns off the managed hooks of the agent. | Remove the setting where you set it: in managed-settings.json, another file in managed-settings.d/, the MDM profile or the claude.ai admin console. The agent never changes these sources. |
| The install stops after enrollment, and the signed configuration is not placed. | poison0 config verify rejected client-config.json. An existing file stays. | Look up the exit code under Reference. |
| The uninstall stops and removes nothing. | It could not remove the agent hooks of every user. | Set PZ_UNINSTALL_FORCE=1 and remove the remaining entries by hand. |
Reference
Environment variables
Set these before the installer runs. A flag, passed after sh -s --, wins over its variable.
| Variable | What it does |
|---|---|
PZ_ENROLL_CODE | The install key from the console. On an enrolled Mac, a new key enrolls it again. |
PZ_APP_ID | Only for a single-use code that came with an app ID. |
PZ_HEADLESS | How confirmation prompts are handled when no desktop user can answer. none (default) decides by the signed-in user, standard always treats the Mac as headless, strict is the strictest. Flag: --headless. |
PZ_DEVICE_NAME | The device name in the console, up to 63 characters, only a-z, 0-9 and -. Without a name, the console shows a placeholder. Instead, PZ_DEVICE_NAME_FROM_HOSTNAME=1 sends the computer name of the Mac (System Settings → General → About → Name), or PZ_DEVICE_NAMES_CSV (file or https URL, header hostname,name) looks the Mac up by computer name, local hostname or hostname and sends only the name from the CSV. If several are set, PZ_DEVICE_NAME wins, then the CSV. They apply at the first enrollment only. More in onboarding. |
PZ_SETUP_AGENTS | Adds the local /poison0 stats command to the listed agents, for example claude,codex. |
PZ_SETUP_STATUSLINE | Set to 1 to add the status line to Claude Code. An existing status line stays. |
PZ_SETUP_EXEC0 | Set to off to keep exec0 off, also after updates. Other values are ignored. Turn it on in the console profile or with sudo poison0 exec0 observe or enforce. |
PZ_SETUP_LEAK0 | Private devices only. Sets the leak0 mode: enforce, observe or off. Without it and without a terminal, leak0 stays off. |
PZ_BACKEND | cpu (default) or gpu. The console profile decides whether the Mac uses the GPU. |
PZ_TIER | enterprise (default) or ultra. With ultra the installer stops with an error, so set Ultra in the console profile. |
PZ_NO_SHORT_ALIAS | Set to 1 to skip the short command p0. |
PZ_FETCH_ONLY | Set to 1 to only download and check the program, without a service and without admin rights. It goes to ./poison0 or to PZ_FETCH_DEST. |
PZ_DRY_RUN | Set to 1 to print the install mode and exit before any change. |
POISONZERO_DATA_DIR | Changes the data directory of the installer and the agent. |
PZ_CONFIG | Path to a signed client-config.json for a private Mac. Flag: --config. |
PZ_QUARANTINE_RETENTION_DAYS | Private devices only. Days a quarantine case is kept, 1 to 3650. Flag: --quarantine-retention-days. |
PZ_AUDIT_MAX_MB | Private devices only. Size in MB at which the audit log rotates, 1 to 1024. Flag: --audit-max-mb. |
Paths and service
| Item | Location |
|---|---|
| The program and its commands. | /usr/local/bin/poison0. The commands poisonzero, p0 and pz link to it. |
| The data directory. | /Library/Application Support/PoisonZero, owner root:wheel. It holds the credentials, the enroll file, the logs and the quarantine store. |
| The service. | The LaunchDaemon com.poisonzero.daemon. It starts at boot and runs as root. |
| The notifier for confirmation prompts. | The LaunchAgent com.poisonzero.notifier in each user session. Without a signed-in user, it starts at the next login. |
| The service log. | daemon.log in the data directory. It rotates at 5 MB. |
| The exec0 hooks for Claude Code. | /Library/Application Support/ClaudeCode/managed-settings.d/50-poisonzero-exec0.json. A Homebrew install under a user-owned prefix uses ~/.claude/settings.json. |
exec0 hooks in Claude Code
The agent never changes your managed-settings.json or other files in managed-settings.d/. To turn exec0 off or on for Claude Code:
# turn off sudo poison0 setup-claude --toolgate-off # turn on sudo poison0 setup-claude --toolgate
Exit codes of the signed configuration
poison0 config verify returns these codes. The installer places the file only on 0 or 6.
| Exit code | Meaning |
|---|---|
| 0 | The file is valid. |
| 6 | The licence is not there yet. The service checks the file at start. |
| 1 | The file cannot be read. |
| 3 | The file is not signed for this device. |
| 4 | The file is outdated or expired. |
| 5 | The file is invalid or too new for this agent version. |
| 7 | The Mac is a cloud device, which ignores the file. |
Read next
Other operating systems: install overview. Hardware: system requirements. Protection per agent: supported agents.