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 Linux

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

~4 min read · Installation & operation

Requirements

RequirementDetails
Processorx86-64 with AVX2 (Intel Haswell, 2013, or newer, AMD Zen or newer), or ARM64 with i8mm, for example AWS Graviton 3 or 4 and Ampere One. AWS Graviton 2 and Ampere Altra are not supported.
KernelKernel 5.13 or newer with Landlock active, as on Ubuntu 22.04, Debian 12 and RHEL 9.6 or newer. Otherwise add landlock to the boot parameter lsm=.
ContainersThe default Docker seccomp profile blocks the Landlock system calls. Use an adjusted profile.
RightsRoot rights. The installer runs 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 machine

Run this command in a 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 machine. If the desktop has no dialog tool for confirmation prompts, it tries to install zenity. 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 machine's hostname, No sends no name. With Ansible 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 machine

  1. Run systemctl status poisonzero. The service should be active. journalctl -u poisonzero shows its log.
  2. Run poison0 doctor in your desktop session. It names what is wrong.
  3. Open the console. The machine 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 machines

Use Ansible or another script that runs as root.

1. Install the agent

Without a terminal, pass the key as an environment variable. On a server without a desktop, also set PZ_HEADLESS.

bashAs root
PZ_ENROLL_CODE="<install-key>" sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"

2. Optional: set up /pz and the status line

PoisonZero sets up the protection for the AI agents itself after installation, in every user account and for all supported agents. If you also want /pz and the status line, run these commands once in the user account. The second one adds the status line.

bashUser
poison0 setup-claude
poison0 setup-claude --statusline-only

Intune (Linux)

Intune runs Bash scripts on Ubuntu Desktop 24.04 and 26.04 and on Red Hat Enterprise Linux 9 and 10. The machine must be enrolled in Intune.

  1. In the console open Devices, choose Download Intune package and then Linux. The console downloads the script.
  2. In Intune, add a script under Devices → Scripts and remediations → Platform scripts → Add → Linux and upload the file.
  3. Choose Root as the execution context. The frequency does not matter; by default Intune runs the script every 15 minutes. Enter, for example, 3 for Execution retries.
  4. Assign the script to a device group.

The script does not enroll a machine that is already enrolled a second time. On the first run Intune may ask the user for consent. The script contains an install key that every Intune admin with read access to scripts can see. The console lists it as Intune Linux with the date. It is valid for one year; revoke it after the rollout.

Private machines: signed configuration

A private machine 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 Ansible task 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 /etc/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.

Remove a .deb or .rpm install with the package manager. It removes the hooks first.

bashPackages
sudo apt remove poisonzero   # .deb
sudo dnf remove poisonzero   # .rpm
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 /var/lib/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
The engine does not start.Landlock is not active.Turn Landlock on as described under Requirements.
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 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/ 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 machine, 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 machine as headless, strict is the strictest. Flag: --headless.
PZ_DEVICE_NAMEThe device name in the console, stored as lowercase letters, digits and hyphens, up to 63 characters. The installer shows how the name is stored. Other naming options are 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 machine 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 root 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 machine. 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./var/lib/poisonzero, owner poisonzero:poisonzero. It holds the credentials, the logs and the quarantine store.
The configuration directory./etc/poisonzero. It holds the enroll file /etc/poisonzero/enroll and the signed configuration.
The service.The systemd unit poisonzero.service. It starts at boot and runs as root.
The notifier for confirmation prompts.It starts in each desktop session through XDG autostart, /etc/xdg/autostart/poisonzero-notifier.desktop.
The service log.daemon.log in the data directory, rotated at 5 MB. The same lines go to the journal.
The exec0 hooks for Claude Code.A system install (install.sh, .deb or .rpm) uses the separate file /etc/claude-code/managed-settings.d/50-poisonzero-exec0.json, also on WSL. A Homebrew install under a user-owned prefix uses ~/.claude/settings.json instead.

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 machine is a cloud device, which ignores the file.

Other operating systems: install overview. Hardware: system requirements. Engine isolation: Linux sandbox.