Install the poison0 agent on Windows
Install, roll out, check and remove the poison0 agent on Windows, by hand or with Intune.
Requirements
| Requirement | Details |
|---|---|
| Processor | Windows x64 with AVX2 (Intel Haswell, 2013, or newer, AMD Zen or newer). Windows on ARM is not supported. |
| Rights | PowerShell as Administrator. Windows PowerShell 5.1 and PowerShell 7 both work. |
| File system | The data directory must be on an NTFS volume. |
| Microsoft Defender | Path exclusions, set before the install, because the program is not code-signed. See step 1 under Roll out to many devices. |
| Install key | An install key from the console, under Devices → Roll out many devices with a key. |
These AI agents get hooks on Windows. All protections per agent: supported agents.
| Agent | Hooks on Windows |
|---|---|
| Claude Code | Supported. The /pz commands, the status line and leak0 are set up per user. |
| Codex | Supported from Codex CLI 0.159. |
| Gemini CLI, Antigravity, GitHub Copilot CLI, Windsurf / Devin | Supported. |
| Cursor, Cortex Code, Kiro, Cline | No hooks on Windows. Memory protection still covers their files. |
| OpenCode, OpenClaw, Kilo 7.x | Kilo 7.x: Supported. The plugin loads from a managed copy in C:\ProgramData\kilo that only administrators can change; a per-user copy stands back. Starting Kilo without plugins (KILO_PURE, --pure) is blocked. OpenCode, OpenClaw: Not checked on Windows yet. |
Install one device
Run this command in PowerShell as Administrator.
$env:PZ_ENROLL_CODE="<install-key>" irm https://poisonzero.com/install.ps1 | iex
The installer checks the program against SHA256SUMS and stops on a mismatch. Then it enrolls the device and registers the service.
In an interactive console, the installer asks for the acceleration and the AI agents to set up. It also asks whether to send the device name to the console. You answer Yes or No, there is no default. Yes sends the computer name, No sends no name. Without a console it asks nothing, installs for the CPU and sends no name.
Check the device
- Run
Get-ScheduledTask -TaskName PoisonZero. The task should be running. - Run
poison0 doctorin the user's session. It names what is wrong. - Open the console. The device 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 devices
Use Intune and follow these steps in order.
1. Set the Microsoft Defender exclusions
Exclude these three paths before you assign the app. Process exclusions are not needed.
C:\Program Files\PoisonZero C:\ProgramData\PoisonZero C:\Users\*\AppData\Local\PoisonZero
The * covers every user profile. Do not use %LOCALAPPDATA% or %USERPROFILE%. Defender runs as LocalSystem and expands them to C:\Windows\System32\config\systemprofile.
- In Intune, open Endpoint security → Antivirus → Create policy.
- Select the platform Windows and the profile Microsoft Defender Antivirus exclusions.
- Add the three paths under Excluded paths.
- Assign the policy to the same groups as the app.
To check a device, use the commands under Troubleshooting. For Group Policy instead of Intune, see Reference.
2. Get an install key
- In the console, open Devices → Roll out many devices with a key and select Generate key.
- Copy the key. The console shows it only once.
- Save it in a file for the next step, for example
C:\secure\code.txt.
The key is valid for 30 days and enrolls devices up to your plan's limit, on Enterprise any number. Each device gets its own identity.
To create the key from a script, use the Management API as shown under Alternative.
3. Download the ready package
Download the two app files and the two detection scripts of the current release and check their SHA-256. They hold no install key, and detect.ps1 already carries the release version.
$base = 'https://poisonzero.com/dl/latest'
New-Item -ItemType Directory -Force C:\pz-out | Out-Null
foreach ($f in 'install.intunewin', 'user-setup.intunewin', 'detect.ps1', 'detect-user.ps1') {
Invoke-WebRequest "$base/$f" -OutFile "C:\pz-out\$f"
Invoke-WebRequest "$base/$f.sha256" -OutFile "C:\pz-out\$f.sha256"
$want = ((Get-Content "C:\pz-out\$f.sha256" -TotalCount 1) -split '\s+')[0]
if ((Get-FileHash "C:\pz-out\$f" -Algorithm SHA256).Hash -ne $want) { throw "SHA-256 mismatch: $f" }
}
Invoke-RestMethod "$base/VERSION"The last line prints the release version for the install command. For a fixed release, replace latest with v<version>.
Download the package in the console
- In the console open Devices, expand Roll out many devices with a key and select Download Intune package. Leave Windows selected.
- Optional: tick Use the computer name as device name. Then select Download. The console downloads the finished package as an
.intunewinfile with a new install key inside. - Copy the values the console then shows into the Intune apps of step 4. The Install command is just
install.cmd, because the key is already in the package. The links todetect.ps1,user-setup.intunewinanddetect-user.ps1are shown there too.
This replaces steps 2 and 3, step 1 stays. The package contains an install key that every Intune admin can see in the app. The console lists it as Intune with the date. It is valid for one year; revoke it after the rollout.
Alternative: build the package yourself
With your own package the key goes into the package (installcode.txt) instead of the install command.
Download the zip, check its SHA-256 and unpack it:
$base = 'https://poisonzero.com/dl/latest'
Invoke-WebRequest "$base/poisonzero-intune.zip" -OutFile poisonzero-intune.zip
Invoke-WebRequest "$base/poisonzero-intune.zip.sha256" -OutFile poisonzero-intune.zip.sha256
$want = ((Get-Content poisonzero-intune.zip.sha256 -TotalCount 1) -split '\s+')[0]
if ((Get-FileHash poisonzero-intune.zip -Algorithm SHA256).Hash -ne $want) { throw 'SHA-256 mismatch' }
Expand-Archive poisonzero-intune.zip -DestinationPath C:\pz-srcFor a fixed release, replace latest with v<version>, for example v1.16.55.
Build the package folder. The key goes into installcode.txt. Windows PowerShell 5.1 (built into Windows) is enough; PowerShell 7 is optional.
Get-Content C:\secure\code.txt -TotalCount 1 | powershell -NoProfile -ExecutionPolicy Bypass -File C:\pz-src\build-package.ps1 -Out C:\pz-intune -Version 1.16.55 -InstallCodeFromStdin
Or create the key with the Management API and build the package in one command. The key is never printed.
$h = @{ Authorization = "Bearer $env:PZ_API_KEY" }
(Invoke-RestMethod -Method Post https://poisonzero.com/api/v1/install-codes -Headers $h -ContentType 'application/json' -Body '{"deviceMode":"cloud"}').code | powershell -NoProfile -ExecutionPolicy Bypass -File C:\pz-src\build-package.ps1 -Out C:\pz-intune -Version 1.16.55 -InstallCodeFromStdinBuild the two app files with Microsoft's Win32 Content Prep Tool, which is not in the zip. It writes install.intunewin and user-setup.intunewin to C:\pz-out.
IntuneWinAppUtil.exe -c C:\pz-intune -s install.cmd -o C:\pz-out -q IntuneWinAppUtil.exe -c C:\pz-intune -s user-setup.ps1 -o C:\pz-out -q
.intunewin file contains the install key. Treat it like the key. Revoke the key in the console after the rollout.4. Create the Intune apps
Create two Win32 apps and assign both once the Defender policy shows as applied. The main app installs the agent as SYSTEM. The per-user app sets up the AI agents in each user account.
The key in the install command is visible to Intune administrators in the app settings. Revoke it in the console after the rollout.
By default no device name is sent. To send one, add -DeviceNameFromHostname (the computer name; your explicit choice, PoisonZero does not recommend it) or -DeviceNamesCsv <https URL> (a CSV with the header hostname,name; only the name is sent) to the install command.
| Main app | Value |
|---|---|
| App file | install.intunewin. |
| Install command | Recommended: install.cmd -Version latest -InstallCode "<install-key>", which installs the latest release (packages from 1.16.88 on; with an older package leave out -Version). To pin a release instead: install.cmd -Version 1.16.55 -InstallCode "<install-key>", with the version from step 3. With your own package, leave out -InstallCode: the key comes from installcode.txt. |
| Uninstall command | uninstall.cmd. It removes the hooks of every user first. |
| Install behavior | System. The installer needs SYSTEM rights. |
| Device restart behavior | No specific action. The install needs no restart. |
| Return codes | 0 means success. 1 means failure, including a failed enrollment. |
| Operating system architecture | Select x64 only. |
| Detection rule | Custom script detect.ps1. Set Run script as 32-bit process on 64-bit clients to No. |
| Per-user app | Value |
|---|---|
| App file | user-setup.intunewin. |
| Install command | powershell.exe -NoProfile -ExecutionPolicy Bypass -File user-setup.ps1. Add -StatusLine for the Claude Code status line. |
| Uninstall command | cmd.exe /c exit 0, because Intune requires one. The main app removes the hooks. |
| Install behavior | User. The script needs no administrator rights. |
| Dependencies | The PoisonZero app, with Automatically install set to Yes. |
| Return codes | 0 means success. 1 means failure. |
| Detection rule | Custom script detect-user.ps1, which checks for %USERPROFILE%\.claude\commands\pz.md. Set Run script as 32-bit process on 64-bit clients to No. |
Configuration Manager
Use the package folder in an Application with a script installer that runs as SYSTEM, with the values of the main app. Deploy user-setup.ps1 in the user context with detect-user.ps1 and a dependency on that Application.
Private devices: signed configuration
A private device 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. The console shows a script that places the file.
- Create an app with that script and add exit code 6 as a success code. 6 means the device checks the file later.
- Assign the app to private devices only. On a cloud device the script ends with 7, a failure.
On a single device, set PZ_CONFIG to the file path before you run the install command. The file goes to %ProgramData%\PoisonZero\client-config.json, readable by SYSTEM and Administrators only.
Update
Cloud devices update themselves. To turn this off per device, use Settings → Protection & Devices → Updates in the console. We have not tested this setting on Windows yet. 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 poison0.exe. poisonzero.exe stays as a copy, and folder exclusions stay valid. For file or process exclusions, add poison0.exe and keep poisonzero.exe, because agent hooks still call it.
Uninstall
Run this command in PowerShell as Administrator. With Intune, uninstall the app instead, which runs uninstall.cmd.
& ([scriptblock]::Create((irm https://poisonzero.com/install.ps1))) -Uninstall
The uninstall first removes the agent hooks of every user and stops if that fails. Then it removes the scheduled task, the notifier, the commands, the program and the data directory.
A Scoop install is removed with scoop uninstall poisonzero.
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 %ProgramData%\PoisonZero-quarantine, readable by SYSTEM and Administrators 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 install ends with exit code 1 and not enrolled: <reason> in its log. | The enrollment failed, for example with device_limit, expired, revoked or max_redemptions. A first install is rolled back. | Fix the named cause in the console, for example with a new install key, and install again. |
The install fails with code_unknown. | You used the enrollment code from a device page without its app ID. | Pass both: install.cmd -AppId <app-id> -InstallCode "<code>". |
| A device you revoked does not enroll again. | An enrolled device gets no key on reinstall or update. | Add -ForceEnroll to the install command once. |
| The console shows no device name after the rollout. | PoisonZero sends no device name by default. | Rename the device in the console, or add -DeviceNameFromHostname or -DeviceNamesCsv to the install command. It applies when a device enrolls. |
| The install key is visible in Intune and in the logs on the devices. | You passed it with install.cmd -InstallCode. | Build the package with -InstallCodeFromStdin. |
| Intune reinstalls the app on every check. | $MinVersion in detect.ps1 is higher than the installed version. | Keep $MinVersion at or below the installed version. build-package.ps1 -Version sets it. |
| Intune reports the per-user app as failed. | The PoisonZero app is not installed on the device, so the script ends with exit 1. The per-user app needs the dependency on the PoisonZero app. | Add the dependency on the PoisonZero app. A user without Claude Code is detected right away, because the script prepares the profile in advance. |
| Defender blocks or removes the program, with event ID 1116 or 1117. | Defender flagged the unsigned program in a path that no exclusion covers. | Check the exclusions with the commands below this table. Use exactly the three paths from step 1. |
Defender blocks your exclusion command as Trojan:Win32/PowExcEnv.RXH!MTB. | You set the exclusions with powershell -EncodedCommand ... Add-MpPreference ..., so they are not set. | Set them with Intune or Group Policy. |
Get-MpPreference shows no exclusion paths. | Without elevation it shows a notice instead. HideExclusionsFromLocalAdmins hides the paths even from administrators, but they still apply. | Run it as Administrator, or test one path with MpCmdRun.exe -CheckExclusion. |
poison0 doctor shows that the model download failed. | The background download after the first install did not finish. | Run poison0 model as Administrator to retry now. poison0 doctor shows the reason. |
poison0 doctor reports "GPU present but no Vulkan driver". | vulkan-1.dll is missing in the system directory, or no Vulkan driver is registered. | Install or update the GPU vendor driver. Until then the engine runs on the CPU and inject0 stays off. |
poison0 exec0 status shows that Claude Code does not call the exec0 hook. | Claude Code settings come from Group Policy or Intune (HKLM\SOFTWARE\Policies\ClaudeCode) or the claude.ai admin console. Claude Code then ignores 50-poisonzero-exec0.json. | Set "managedSourcesBehavior": "merge" there (Claude Code 2.1.242 or later), or copy the content of the file into it. poison0 doctor warns inject0 failure hook missing: Claude Code has no PostToolUseFailure hook entry, so inject0 does not check the output of failed tool calls. With settings from Group Policy or Intune (HKLM\SOFTWARE\Policies\ClaudeCode), managed-settings.json or the claude.ai admin console, that source must carry the entry. Add the PostToolUseFailure entry from 50-poisonzero-exec0.json next to PostToolUse in that source. Without central settings, run poison0 setup-claude --toolgate. |
poison0 status or poison0 doctor shows Codex as not protected. | Codex CLI is older than 0.159. Or 8.3 short names are off on the system volume, so Codex cannot start the hook from C:\Program Files\PoisonZero, whose path has a space. | Update Codex CLI to 0.159 or later. Without 8.3 names, exec0 cannot protect Codex on this device. Turning 8.3 names on later does not help. |
| 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. |
Run these in an elevated PowerShell. MpCmdRun.exe is in the Defender platform folder, %ProgramData%\Microsoft\Windows Defender\Platform\<version>.
Get-MpPreference | Select-Object -ExpandProperty ExclusionPath
MpCmdRun.exe -CheckExclusion -Path C:\ProgramData\PoisonZero
Get-WinEvent -FilterHashtable @{LogName='Microsoft-Windows-Windows Defender/Operational'; Id=1116,1117} -ErrorAction SilentlyContinue | Where-Object Message -like '*PoisonZero*' | Format-List TimeCreated, Id, MessageReference
Version pin and detection
| Parameter | What it does |
|---|---|
-Version | latest installs the latest release, the same as leaving it out. A version such as 1.16.55 installs this release instead and never replaces a newer installed program; a version that was never published is refused before the download. With build-package.ps1 a version also sets $MinVersion in detect.ps1. |
-Sha256 <hex> | Checks the program against a hash from a source you trust, only with -Version. SHA256SUMS comes from the same server and only catches a damaged download. |
detect.ps1 reports the app as installed when the program exists, the device is enrolled, the version is at least $MinVersion and the task PoisonZero exists. Newer versions count, because cloud devices update themselves.
Environment variables
Set them before you run the installer. With install.ps1 run as a file, -Version, -Sha256, -Config and -Uninstall win over their variables. The Intune install.cmd clears PZ_ENROLL_CODE, PZ_APP_ID, PZ_VERSION, PZ_SHA256 and PZ_UNINSTALL, so use its parameters.
| Variable | What it does |
|---|---|
PZ_ENROLL_CODE | The install key from the console. On an enrolled device, a new key enrolls it again. |
PZ_APP_ID | Only for a single-use code that came with an app ID. |
PZ_VERSION | Like -Version, for example latest or 1.16.55. |
PZ_SHA256 | Like -Sha256. Use it only with PZ_VERSION. |
PZ_ALLOW_DOWNGRADE | Set to 1 to let a pinned release replace a newer installed program. |
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 device as headless, strict is the strictest. |
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, if someone is signed in. |
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 poison0 exec0 observe or enforce. |
PZ_SETUP_LEAK0 | Private devices only. Sets the leak0 mode: enforce, observe or off. Without it and without a console, leak0 stays off. |
PZ_BACKEND | cpu (default) or gpu. With gpu the installer warns when it finds no Vulkan driver. |
PZ_TIER | enterprise (default) or ultra. With ultra the install stops when the graphics adapter has less than 8 GB video memory or no Vulkan driver. |
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 admin rights. It goes to .\poison0.exe or to PZ_FETCH_DEST. |
PZ_DRY_RUN | Set to 1 to print the install mode and exit before any change. |
PZ_CONFIG | Path to a signed client-config.json for a private device. |
PZ_QUARANTINE_RETENTION_DAYS | Private devices only. Days a quarantine case is kept, 1 to 3650. |
PZ_AUDIT_MAX_MB | Private devices only. Size in MB at which the audit log rotates, 1 to 1024. |
PZ_UNINSTALL | Set to 1 to uninstall through irm ... | iex, without arguments. |
Paths and service
| Item | Location |
|---|---|
| The program and its commands. | C:\Program Files\PoisonZero\poison0.exe, with pz-dialog.exe. poisonzero.exe next to it is a copy for scripts and hooks that call it. The folder and its subfolder bin with p0 and pz are on the system PATH. |
| The data directory. | C:\ProgramData\PoisonZero, readable by all users except a few files such as the enrollment file and client-config.json. It holds the credentials, the engine, the logs and the quarantine store. |
| The per-user folder. | %LOCALAPPDATA%\PoisonZero in each profile. It holds the notifier state and the dialog log. |
| The service. | The scheduled task PoisonZero. It runs as SYSTEM at startup, restarts up to 3 times at 1-minute intervals and is started again every 5 minutes. |
| The notifier for confirmation prompts. | It starts at sign-in in each user session through the Run registry value PoisonZeroNotifier. |
| The service log. | daemon.log in the data directory, rotated at 5 MB. It is the only service log. |
| The install log. | The installer writes to standard output. Under Intune it ends up in the Intune Management Extension logs. |
| The exec0 hooks for Claude Code. | C:\Program Files\ClaudeCode\managed-settings.d\50-poisonzero-exec0.json. |
GPU and Ultra
| Item | Behavior |
|---|---|
| GPU engine | On Windows the GPU engine uses Vulkan; Ultra needs a Vulkan driver and at least 8 GB video memory; inject0 runs only on the GPU, needs a Vulkan driver from Intel, AMD or NVIDIA, and without a suitable GPU reports inject0: off (no suitable GPU) and has no CPU fallback. |
| Console profile | It sets whether a device uses the GPU or Ultra. If it asks for the GPU and none is supported, the engine does not start, with no CPU fallback. |
| exec0 | Runs on the CPU and needs no GPU (Enterprise). |
| Sandbox | On the GPU (Ultra or inject0), the engine runs without the AppContainer. See Windows sandbox. |
exec0 for Claude Code
Turn exec0 off or on for Claude Code in PowerShell as Administrator:
# turn off poison0 setup-claude --toolgate-off # turn on poison0 setup-claude --toolgate
Defender exclusions with Group Policy
- Open Computer Configuration → Administrative Templates → Windows Components → Microsoft Defender Antivirus → Exclusions → Path Exclusions. Windows 10 before version 2004 shows Windows Defender Antivirus in this path.
- Select Enabled, then Show....
- Add each path as Value name, with the Value
0. - Run
gpupdate /forceon the device.
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 device is a cloud device, which ignores the file. |
Read next
Other operating systems: install overview. Hardware: system requirements. Engine isolation: Windows sandbox.