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 Windows

Install, roll out, check and remove the poison0 agent on Windows, by hand or with Intune.

~7 min read · Installation & operation

Requirements

RequirementDetails
ProcessorWindows x64 with AVX2 (Intel Haswell, 2013, or newer, AMD Zen or newer). Windows on ARM is not supported.
RightsPowerShell as Administrator. Windows PowerShell 5.1 and PowerShell 7 both work.
File systemThe data directory must be on an NTFS volume.
Microsoft DefenderPath exclusions, set before the install, because the program is not code-signed. See step 1 under Roll out to many devices.
Install keyAn 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.

AgentHooks on Windows
Claude CodeSupported. The /pz commands, the status line and leak0 are set up per user.
CodexSupported from Codex CLI 0.159.
Gemini CLI, Antigravity, GitHub Copilot CLI, Windsurf / DevinSupported.
Cursor, Cortex Code, Kiro, ClineNo hooks on Windows. Memory protection still covers their files.
OpenCode, OpenClaw, Kilo 7.xKilo 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.

powershellPowerShell 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

  1. Run Get-ScheduledTask -TaskName PoisonZero. The task should be running.
  2. Run poison0 doctor in the user's session. It names what is wrong.
  3. 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.

textPath exclusions
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.

  1. In Intune, open Endpoint security → Antivirus → Create policy.
  2. Select the platform Windows and the profile Microsoft Defender Antivirus exclusions.
  3. Add the three paths under Excluded paths.
  4. 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

  1. In the console, open Devices → Roll out many devices with a key and select Generate key.
  2. Copy the key. The console shows it only once.
  3. 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.

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

  1. In the console open Devices, expand Roll out many devices with a key and select Download Intune package. Leave Windows selected.
  2. Optional: tick Use the computer name as device name. Then select Download. The console downloads the finished package as an .intunewin file with a new install key inside.
  3. 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 to detect.ps1, user-setup.intunewin and detect-user.ps1 are 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:

powershellPowerShell
$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-src

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

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

powershellPowerShell
$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 -InstallCodeFromStdin

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

powershellPowerShell
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
The .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 appValue
App fileinstall.intunewin.
Install commandRecommended: 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 commanduninstall.cmd. It removes the hooks of every user first.
Install behaviorSystem. The installer needs SYSTEM rights.
Device restart behaviorNo specific action. The install needs no restart.
Return codes0 means success. 1 means failure, including a failed enrollment.
Operating system architectureSelect x64 only.
Detection ruleCustom script detect.ps1. Set Run script as 32-bit process on 64-bit clients to No.
Per-user appValue
App fileuser-setup.intunewin.
Install commandpowershell.exe -NoProfile -ExecutionPolicy Bypass -File user-setup.ps1. Add -StatusLine for the Claude Code status line.
Uninstall commandcmd.exe /c exit 0, because Intune requires one. The main app removes the hooks.
Install behaviorUser. The script needs no administrator rights.
DependenciesThe PoisonZero app, with Automatically install set to Yes.
Return codes0 means success. 1 means failure.
Detection ruleCustom 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

We have not tested Configuration Manager (SCCM) yet.

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.

  1. In the console, open the profile and select Export for private devices. The console shows a script that places the file.
  2. Create an app with that script and add exit code 6 as a success code. 6 means the device checks the file later.
  3. 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.

powershellPowerShell as Administrator
& ([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.

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 %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

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

powershellPowerShell as Administrator
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, Message

Reference

Version pin and detection

ParameterWhat it does
-Versionlatest 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.

VariableWhat it does
PZ_ENROLL_CODEThe install key from the console. On an enrolled device, a new key enrolls it again.
PZ_APP_IDOnly for a single-use code that came with an app ID.
PZ_VERSIONLike -Version, for example latest or 1.16.55.
PZ_SHA256Like -Sha256. Use it only with PZ_VERSION.
PZ_ALLOW_DOWNGRADESet to 1 to let a pinned release replace a newer installed program.
PZ_HEADLESSHow 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_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, if someone is signed in.
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 poison0 exec0 observe or enforce.
PZ_SETUP_LEAK0Private devices only. Sets the leak0 mode: enforce, observe or off. Without it and without a console, leak0 stays off.
PZ_BACKENDcpu (default) or gpu. With gpu the installer warns when it finds no Vulkan driver.
PZ_TIERenterprise (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_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 admin rights. It goes to .\poison0.exe or to PZ_FETCH_DEST.
PZ_DRY_RUNSet to 1 to print the install mode and exit before any change.
PZ_CONFIGPath to a signed client-config.json for a private device.
PZ_QUARANTINE_RETENTION_DAYSPrivate devices only. Days a quarantine case is kept, 1 to 3650.
PZ_AUDIT_MAX_MBPrivate devices only. Size in MB at which the audit log rotates, 1 to 1024.
PZ_UNINSTALLSet to 1 to uninstall through irm ... | iex, without arguments.

Paths and service

ItemLocation
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

ItemBehavior
GPU engineOn 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 profileIt 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.
exec0Runs on the CPU and needs no GPU (Enterprise).
SandboxOn 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:

powershellexec0 for Claude Code, as Administrator
# turn off
poison0 setup-claude --toolgate-off
# turn on
poison0 setup-claude --toolgate

Defender exclusions with Group Policy

  1. 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.
  2. Select Enabled, then Show....
  3. Add each path as Value name, with the Value 0.
  4. Run gpupdate /force on 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 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 device is a cloud device, which ignores the file.

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