Talk this topic through with an AI

You get an answer from the documentation and the page it comes from.

Installation & operation

Install the poison0 agent on macOS

Install, roll out, check and remove the poison0 agent on a Mac.

~4 min read · Installation & operation

Requirements

RequirementDetails
ProcessorApple M2 or newer, or an Intel Mac with AVX2 (Intel Haswell, 2013, or newer). Apple M1 is not supported.
RightsAdministrator rights. The installer runs as root through sudo.
Install keyAn install key from the console, under Devices → Roll out many devices with a key.
AI agentsAt least one AI agent from supported agents.

Install one Mac

Run this command in the Terminal.

bashTerminal
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

  1. Run launchctl print system/com.poisonzero.daemon. The service should be running.
  2. Run poison0 doctor in your desktop session. It names what is wrong.
  3. 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.

  1. In the console open Devices, expand Roll out many devices with a key and select Download Intune package. Choose the macOS tab.
  2. Optional: tick Use the computer name as device name before you download the profile.
  3. Under 1. Download package, download the package from the link.
  4. Under 2. Download profile, download the profile with Download.

Steps in Intune:

  1. Open Apps → macOS → Add, choose Line-of-business app and upload the package.
  2. Assign the app to a device group under Required.
  3. Open Devices → macOS → Configuration → Create → New policy. Choose the profile type Templates → Custom and the deployment channel Device channel. Upload the .mobileconfig file.
  4. Assign the profile to the same device group.

Steps in Jamf Pro:

  1. Upload the package under Settings → Computer Management → Packages.
  2. 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.
  3. Under Computers → Configuration Profiles → Upload, upload the .mobileconfig file.
  4. 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.

bashJamf or Intune, as root
#!/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.

  1. In the console open Devices, choose Download Intune package and the macOS tab. Expand Other ways and download the script.
  2. In Intune, add a script under Devices → macOS → Scripts → Add and upload the file.
  3. 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.
  4. 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.

  1. In the console, open the profile and select Export for private devices.
  2. Pass the file to the installer with PZ_CONFIG, as shown below.
  3. Or place it with the Jamf script that the console shows after the export.
bashTerminal
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

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

bashHomebrew
poison0 remove-agent-integration && brew uninstall poisonzero
Do not delete the program by hand. Claude Code hooks that point to a missing program block every tool call.

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

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

VariableWhat it does
PZ_ENROLL_CODEThe install key from the console. On an enrolled Mac, a new key enrolls it again.
PZ_APP_IDOnly for a single-use code that came with an app ID.
PZ_HEADLESSHow 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_NAMEThe 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_AGENTSAdds the local /poison0 stats command to the listed agents, for example claude,codex.
PZ_SETUP_STATUSLINESet to 1 to add the status line to Claude Code. An existing status line stays.
PZ_SETUP_EXEC0Set 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_LEAK0Private devices only. Sets the leak0 mode: enforce, observe or off. Without it and without a terminal, leak0 stays off.
PZ_BACKENDcpu (default) or gpu. The console profile decides whether the Mac uses the GPU.
PZ_TIERenterprise (default) or ultra. With ultra the installer stops with an error, so set Ultra in the console profile.
PZ_NO_SHORT_ALIASSet to 1 to skip the short command p0.
PZ_FETCH_ONLYSet 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_RUNSet to 1 to print the install mode and exit before any change.
POISONZERO_DATA_DIRChanges the data directory of the installer and the agent.
PZ_CONFIGPath to a signed client-config.json for a private Mac. Flag: --config.
PZ_QUARANTINE_RETENTION_DAYSPrivate devices only. Days a quarantine case is kept, 1 to 3650. Flag: --quarantine-retention-days.
PZ_AUDIT_MAX_MBPrivate devices only. Size in MB at which the audit log rotates, 1 to 1024. Flag: --audit-max-mb.

Paths and service

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

bashexec0 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 codeMeaning
0The file is valid.
6The licence is not there yet. The service checks the file at start.
1The file cannot be read.
3The file is not signed for this device.
4The file is outdated or expired.
5The file is invalid or too new for this agent version.
7The Mac is a cloud device, which ignores the file.

Other operating systems: install overview. Hardware: system requirements. Protection per agent: supported agents.