Install the poison0 agent on Linux
Install, roll out, check and remove the poison0 agent on Linux.
Requirements
| Requirement | Details |
|---|---|
| Processor | x86-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. |
| Kernel | Kernel 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=. |
| Containers | The default Docker seccomp profile blocks the Landlock system calls. Use an adjusted profile. |
| Rights | Root rights. The installer runs 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 machine
Run this command in a 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 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
- Run
systemctl status poisonzero. The service should be active.journalctl -u poisonzeroshows its log. - Run
poison0 doctorin your desktop session. It names what is wrong. - 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.
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.
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.
- In the console open Devices, choose Download Intune package and then Linux. The console downloads the script.
- In Intune, add a script under Devices → Scripts and remediations → Platform scripts → Add → Linux and upload the file.
- 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.
- 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.
- 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 Ansible task 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 /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
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.
sudo apt remove poisonzero # .deb sudo dnf remove poisonzero # .rpm
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
| Symptom | Cause | Fix |
|---|---|---|
| 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.
| Variable | What it does |
|---|---|
PZ_ENROLL_CODE | The install key from the console. On an enrolled machine, 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 machine as headless, strict is the strictest. Flag: --headless. |
PZ_DEVICE_NAME | The 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_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 machine 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 root 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 machine. 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. | /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:
# 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 machine is a cloud device, which ignores the file. |
Read next
Other operating systems: install overview. Hardware: system requirements. Engine isolation: Linux sandbox.