Installation & operation

Installing PoisonZero: complete reference

PoisonZero installs a small daemon on each device that watches your agents' memory files locally. This page documents the installer end to end: the quick-install commands, every environment variable, the data directory per operating system, the service that runs the daemon, and how to roll it out unattended.

~9 min read · Installation & operation

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

Service install needs elevated rights: root (sudo) on Linux/macOS, an Administrator PowerShell on Windows. Use PZ_FETCH_ONLY=1 to only download and verify.

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 panel (or use a legacy per-device code), then run the command for your platform:

bashTerminal

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

powershellPowerShell

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

Updates run automatically. Install once per device; re-run only to change enrollment or force a binary swap.

Install codes

Create an install code in the panel, 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 panel does not display it again.
Revocable: revoke it in the panel to stop further redemptions immediately; already-enrolled devices keep working.
No app ID needed: the backend assigns each device its identity at redemption.

The legacy flow, creating a device in the panel to get a matching app ID and a single-use code, still works unchanged. Use it for older installers or integrations already built around it.

Environment variables

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

Variable	Values	Default	Effect
`PZ_ENROLL_CODE`	install code	none	The install code from the panel. Required for a fresh enrollment; on its own it is enough, since the backend assigns the device identity. Passing a fresh one again on an enrolled device forces a deliberate re-enroll.
`PZ_APP_ID`	app id	none	Legacy and optional: only needed together with an older per-device code minted before install codes. Ignored on its own.
`PZ_HEADLESS`	`none`, `standard`, `strict`	`none`	Pins the user confirmation-prompt handling on a machine with no desktop user to answer prompts. `none` auto-detects from the logged-in user; `standard`/`strict` write a `headlessmode` file the daemon reads.
`PZ_BACKEND`	`cpu`, `gpu`	`cpu`	Acceleration backend. CPU-only is the recommended, most secure default. GPU is opt-in and prints a security disclaimer; the GPU engine is not released yet.
`PZ_TIER`	`enterprise`, `ultra`	`enterprise`	Product tier. `ultra` implies GPU and is fail-closed with no CPU fallback; `enterprise` with GPU falls back to a working CPU-only install.
`PZ_FETCH_ONLY`	`1`	unset	Download and verify the binary only, then exit. No service is installed, so no elevated rights are needed.
`PZ_FETCH_DEST`	path	`./poisonzero` (`.\poisonzero.exe` on Windows)	Destination path for the verified binary when `PZ_FETCH_ONLY=1`.
`PZ_SETUP_AGENTS`	comma list, e.g. `claude,codex`	unset	Wires the local `/poisonzero` stats command into the listed agents (Claude Code, Codex, Gemini, Cursor). Fully local, opt-in.
`PZ_SETUP_STATUSLINE`	`1`	unset	Adds the PoisonZero status line to Claude Code (`~/.claude/settings.json`). An existing status line is never replaced.
`PZ_DRY_RUN`	`1`	unset	Prints the resolved mode (`fresh`/`re-enroll`/`upgrade`) and exits before any side effect. Useful for testing automation.
`POISONZERO_DATA_DIR`	path	per-OS default (see below)	Overrides the data directory the daemon and installer use.

Linux/macOS also accept a --headless none|standard|strict flag (wins over PZ_HEADLESS); the Windows deploy script takes -Headless.

Data directory and files

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

OS	Data directory	Owner
Linux	`/var/lib/poisonzero` (enroll file at `/etc/poisonzero/enroll`)	`poisonzero:poisonzero`
macOS	`/Library/Application Support/PoisonZero`	`root:wheel`
Windows	`<ProgramData>\PoisonZero`	SYSTEM / Administrators

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:

OS	Type	Name & status command
Linux	systemd unit (root)	`poisonzero.service` · `systemctl status poisonzero`
macOS	launchd LaunchDaemon	`com.poisonzero.daemon` · `launchctl print system/com.poisonzero.daemon`
Windows	Scheduled Task (SYSTEM, at boot)	`PoisonZero` · `Get-ScheduledTask -TaskName PoisonZero`

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:

bashUnattended

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

powershellUnattended

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

Add PZ_DRY_RUN=1 to print the resolved mode (fresh/re-enroll/upgrade) and exit before any change.

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

bashFetch only

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

powershellFetch only

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

Checksum verification is mandatory on every path; a tampered or truncated download is never installed.

Verify the device

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

Uninstall

Stop the service, then remove the binary and data directory:

bashUninstall

sudo systemctl disable --now poisonzero.service
sudo rm -f /usr/local/bin/poisonzero
sudo rm -rf /var/lib/poisonzero /etc/poisonzero

bashUninstall

sudo launchctl bootout system /Library/LaunchDaemons/com.poisonzero.daemon.plist
sudo rm -f /Library/LaunchDaemons/com.poisonzero.daemon.plist /usr/local/bin/poisonzero
sudo rm -rf "/Library/Application Support/PoisonZero"

powershellUninstall

Unregister-ScheduledTask -TaskName PoisonZero -Confirm:$false
icacls "$env:ProgramFiles\PoisonZero\poisonzero.exe" /reset
Remove-Item -Recurse -Force "$env:ProgramFiles\PoisonZero", "$env:ProgramData\PoisonZero"

To pause instead of uninstall: the protection is fail-closed by design, so removing the service is the clean way to stop it entirely.

Was this helpful?

Protect every device in one command.

Free for Linux, macOS and Windows. Install once, updates run automatically.

Sign me up

Installing PoisonZero: complete reference

Overview

Quick install

Install codes

Environment variables

Data directory and files

Service / daemon

Unattended install (Intune / SCCM)

Download and verify only

Verify the device

Uninstall

Protect every device in one command.

Related articles