Installing the poison0 agent: complete reference

Overview

What the installer does, in order:

• Downloads the matching daemon binary from https://poisonzero.com/dl/latest (Linux/macOS/Windows, amd64 or arm64).
• Verifies its SHA-256 checksum against the published SHA256SUMS; aborts on any mismatch.
• Installs a privileged service and, optionally, enrolls the device using an install code from the console.

Requirements, checked before install:

• x86-64: AVX2 (Intel Haswell/2013+, AMD Zen+).
• ARM64: i8mm (Apple M2+; Apple M1 not supported).
• Windows: data directory on an NTFS volume.

Quick install

Create an install code in the console (or use a legacy per-device code), then run the command for your platform:

curl -fsSL https://poisonzero.com/install.sh | sudo \
  PZ_ENROLL_CODE="your-code" sh

$env:PZ_ENROLL_CODE="your-code"
irm https://poisonzero.com/install.ps1 | iex

• No code pre-set: the installer prompts for the install code (plus acceleration/tier and headless choices on a real terminal); an app ID is only asked for the legacy per-device pairing.
• An install code is multi-use up to its redemption cap; a legacy per-device code stays single-use.
• Already enrolled, re-run without a new code = upgrade: swaps the binary, restarts the service, keeps your credentials.

Install codes

Create an install code in the console, under Install keys. It is the recommended way to enroll devices:

• Multi-use: one code enrolls devices up to the redemption cap you set when you create it; each enrollment counts against that cap.
• Shown once: copy it when you create it - the console does not display it again.
• Revocable: revoke it in the console to stop further redemptions immediately; already-enrolled devices keep working.
• No app ID needed: the backend assigns each device its identity at redemption.

Environment variables

Pin any option through an environment variable to run the install non-interactively:

Data directory and files

Binary: /usr/local/bin/poisonzero (Linux/macOS), <ProgramFiles>\PoisonZero\poisonzero.exe (Windows). Data directory per OS:

Files inside the data directory:

• credentials - stored device token; its presence marks the device as enrolled and is never overwritten on upgrade.
• enroll - one-time enrollment input (the install code, plus appId for the legacy pairing) consumed by poisonzero enroll on first start.
• headlessmode - present only when standard/strict was pinned; absent or empty = auto-detect.
• vault/ - quarantine store for reverted content.

Service / daemon

Runs as a privileged background service, one mechanism per OS:

• Windows uses a Scheduled Task, not a Windows Service: the Go binary loads its model on first start and would miss the Service Control Manager start timeout.
• A desktop notifier runs in each user session for the user confirmation prompt: XDG autostart (Linux), per-user LaunchAgent (macOS), Run-key VBS wrapper (Windows).

Unattended install (Intune / SCCM)

Set the install code in the environment, then run the same one-liner; with the code present and no terminal, it runs prompt-free:

PZ_ENROLL_CODE="your-code" \
  sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"

$env:PZ_ENROLL_CODE="your-code"
irm https://poisonzero.com/install.ps1 | iex

Download and verify only

PZ_FETCH_ONLY=1 downloads, verifies the SHA-256 checksum and writes the binary without installing a service (no elevated rights):

curl -fsSL https://poisonzero.com/install.sh | PZ_FETCH_ONLY=1 sh
# writes ./poisonzero (override with PZ_FETCH_DEST)

$env:PZ_FETCH_ONLY="1"; irm https://poisonzero.com/install.ps1 | iex
# writes .\poisonzero.exe (override with $env:PZ_FETCH_DEST)

Verify the device

1. Confirm the service is running with the status command for your OS (table above).
2. Open the console: the enrolled device appears in your device list with its status.
3. To move a device to a fresh install code, re-run the installer with a new PZ_ENROLL_CODE - it re-enrolls cleanly.

Uninstall

One command removes everything: first the exec0 file managed-settings.d/50-poisonzero-exec0.json and the Claude Code hooks of every user, then the service, the program and the data directory. If the exec0 file cannot be removed, the uninstall stops and the program stays installed. Run it as administrator (root). Never delete the program by hand: hooks that point to a missing program block every tool call in Claude Code.

curl -fsSL https://poisonzero.com/install.sh | sudo sh -s -- --uninstall

& ([scriptblock]::Create((irm https://poisonzero.com/install.ps1))) -Uninstall

# .deb / .rpm
sudo apt remove poisonzero   # or: sudo dnf remove poisonzero
# Homebrew
poison0 remove-agent-integration && brew uninstall poisonzero
# Scoop
scoop uninstall poisonzero

exec0 hooks in Claude Code

exec0 hooks into Claude Code with three hooks: UserPromptSubmit, PreToolUse and PostToolUse. Where they are registered depends on the type of installation:

• PoisonZero never changes your managed-settings.json and never changes other files in managed-settings.d/.
• Folders PoisonZero creates are writable only by administrators and readable by everyone.

Effect

Policies already delivered centrally

If you already deliver Claude Code policies through one of the following sources, Claude Code by default applies only the highest source and ignores 50-poisonzero-exec0.json:

Turn exec0 off and on for Claude Code

Requires administrator rights. On Windows, run it in a terminal as administrator.

# turn off
sudo poison0 setup-claude --toolgate-off
# turn on
sudo poison0 setup-claude --toolgate

# turn off
poison0 setup-claude --toolgate-off
# turn on
poison0 setup-claude --toolgate