Den poison0-Agenten installieren: vollständige Referenz
Der poison0-Agent ist ein kleiner Daemon auf jedem Gerät, der die Memory-Dateien Ihrer Agenten lokal überwacht. Diese Seite dokumentiert den Installer von Anfang bis Ende: die Befehle für die Schnellinstallation, jede Umgebungsvariable, das Datenverzeichnis je Betriebssystem, den Dienst, der den Daemon ausführt, und wie Sie ihn unbeaufsichtigt ausrollen.
Überblick
Was der Installer tut, der Reihe nach:
- Lädt das passende Daemon-Binary von
https://poisonzero.com/dl/latest(Linux/macOS/Windows,amd64oderarm64). - Verifiziert seine SHA-256-Checksumme gegen die veröffentlichte
SHA256SUMS; bricht bei jeder Abweichung ab. - Installiert einen privilegierten Dienst und enrollt das Gerät optional über einen Installationsschlüssel aus der Konsole.
Die Dienst-Installation braucht erhöhte Rechte: root (
sudo) auf Linux/macOS, eine Administrator-PowerShell auf Windows. Mit PZ_FETCH_ONLY=1 nur herunterladen und verifizieren.Voraussetzungen, die vor der Installation geprüft werden:
- x86-64: AVX2 (Intel Haswell/2013+, AMD Zen+).
- ARM64: i8mm (Apple M2+; Apple M1 nicht unterstützt).
- Windows: Datenverzeichnis auf einem NTFS-Laufwerk.
Schnellinstallation
Erzeugen Sie in der Konsole einen Installationsschlüssel (oder verwenden Sie einen alten Code je Gerät) und führen Sie den Befehl für Ihre Plattform aus:
bashTerminal
curl -fsSL https://poisonzero.com/install.sh | sudo \ PZ_ENROLL_CODE="ihr-code" sh
powershellPowerShell
$env:PZ_ENROLL_CODE="ihr-code" irm https://poisonzero.com/install.ps1 | iex
- Ohne vorab gesetzten Code fragt der Installer nach dem Installationsschlüssel (auf einem echten Terminal zusätzlich Beschleunigungs-/Tier- und Headless-Auswahl); nach einer App-ID wird nur beim alten Verfahren je Gerät gefragt.
- Ein Installationsschlüssel ist mehrfach nutzbar bis zu seiner Einlösungsgrenze; ein alter Code je Gerät bleibt ein Einmal-Code.
- Bereits enrollt und ohne neuen Code erneut ausgeführt = Upgrade: tauscht das Binary, startet den Dienst neu, behält Ihre Credentials.
Updates laufen automatisch. Einmal pro Gerät installieren; erneut ausführen nur, um das Enrollment zu ändern oder einen Binary-Tausch zu erzwingen.
Installationsschlüssel
Erzeugen Sie einen Installationsschlüssel in der Konsole unter Installationsschlüssel. Er ist der empfohlene Weg, Geräte zu enrollen:
- Mehrfach nutzbar: Ein Schlüssel enrollt Geräte bis zu der Einlösungsgrenze, die Sie bei der Erzeugung festlegen; jedes Enrollment zählt auf diese Grenze.
- Nur einmal angezeigt: Kopieren Sie ihn bei der Erzeugung - die Konsole zeigt ihn danach nicht erneut.
- Widerrufbar: In der Konsole widerrufen stoppt sofort weitere Einlösungen; bereits enrollte Geräte laufen weiter.
- Keine App-ID nötig: Das Backend vergibt jedem Gerät seine Kennung erst bei der Einlösung.
Das alte Verfahren - ein Gerät in der Konsole anlegen, um eine passende App-ID und einen Einmal-Code zu erhalten - funktioniert unverändert weiter. Nutzen Sie es für ältere Installer oder bestehende Integrationen.
Umgebungsvariablen
Nageln Sie jede Option über eine Umgebungsvariable fest, um die Installation nicht-interaktiv auszuführen:
| Variable | Werte | Default | Wirkung |
|---|---|---|---|
PZ_ENROLL_CODE | Installationsschlüssel | keiner | Der Installationsschlüssel aus der Konsole. Für ein frisches Enrollment erforderlich; er genügt allein, da das Backend die Gerätekennung vergibt. Wird ein frischer Schlüssel auf einem enrollten Gerät erneut übergeben, erzwingt das ein bewusstes Re-Enroll. |
PZ_APP_ID | App-ID | keiner | Alt und optional: nur zusammen mit einem älteren Code je Gerät nötig, der vor den Installationsschlüsseln geprägt wurde. Allein wird sie ignoriert. |
PZ_HEADLESS | none, standard, strict | none | Nagelt den Nutzer-Dialog-Umgang auf einer Maschine ohne Desktop-Nutzer fest. none erkennt automatisch aus dem angemeldeten Nutzer; standard/strict schreiben eine headlessmode-Datei, die der Daemon liest. |
PZ_BACKEND | cpu, gpu | cpu | Beschleunigungs-Backend. Nur CPU ist der empfohlene, sicherste Standard. GPU ist Opt-in und zeigt einen Sicherheitshinweis; die GPU-Engine ist noch nicht veröffentlicht. |
PZ_TIER | enterprise, ultra | enterprise | Produkt-Tier. ultra impliziert GPU und ist fail-closed ohne CPU-Fallback; enterprise mit GPU fällt auf eine funktionierende Nur-CPU-Installation zurück. |
PZ_FETCH_ONLY | 1 | nicht gesetzt | Lädt und verifiziert nur das Binary und beendet sich dann. Kein Dienst wird installiert, daher sind keine erhöhten Rechte nötig. |
PZ_FETCH_DEST | Pfad | ./poisonzero (.\poisonzero.exe auf Windows) | Zielpfad für das verifizierte Binary bei PZ_FETCH_ONLY=1. |
PZ_SETUP_AGENTS | Komma-Liste, z. B. claude,codex | nicht gesetzt | Klinkt den lokalen /poisonzero-Statistikbefehl in die genannten Agenten ein (Claude Code, Codex, Gemini, Cursor). Rein lokal, Opt-in. |
PZ_SETUP_STATUSLINE | 1 | nicht gesetzt | Fügt die Statusline des poison0-Agenten in Claude Code hinzu (~/.claude/settings.json). Eine bestehende Statusline wird nie ersetzt. |
PZ_DRY_RUN | 1 | nicht gesetzt | Gibt den aufgelösten Modus (fresh/re-enroll/upgrade) aus und beendet sich vor jedem Seiteneffekt. Nützlich, um Automatisierung zu testen. |
POISONZERO_DATA_DIR | Pfad | OS-Default (siehe unten) | Überschreibt das Datenverzeichnis, das Daemon und Installer nutzen. |
Linux/macOS akzeptieren zusätzlich ein Flag
--headless none|standard|strict (gewinnt gegen PZ_HEADLESS); das Windows-Deploy-Skript nimmt -Headless.Datenverzeichnis und Dateien
Binary: /usr/local/bin/poisonzero (Linux/macOS), <ProgramFiles>\PoisonZero\poisonzero.exe (Windows). Datenverzeichnis je OS:
| OS | Datenverzeichnis | Eigentümer |
|---|---|---|
| Linux | /var/lib/poisonzero (enroll-Datei unter /etc/poisonzero/enroll) | poisonzero:poisonzero |
| macOS | /Library/Application Support/PoisonZero | root:wheel |
| Windows | <ProgramData>\PoisonZero | SYSTEM / Administratoren |
Dateien im Datenverzeichnis:
credentials- gespeichertes Geräte-Token; seine Existenz markiert das Gerät als enrollt und wird beim Upgrade nie überschrieben.enroll- Einmal-Enrollment-Eingabe (der Installationsschlüssel, plusappIdbeim alten Verfahren), diepoisonzero enrollbeim ersten Start verbraucht.headlessmode- nur vorhanden, wennstandard/strictfestgenagelt wurde; fehlend oder leer = Auto-Erkennung.vault/- Quarantäne-Speicher für zurückgenommene Inhalte.
Dienst / Daemon
Läuft als privilegierter Hintergrunddienst, ein Mechanismus je OS:
| OS | Typ | Name & Statusbefehl |
|---|---|---|
| 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, bei Boot) | PoisonZero · Get-ScheduledTask -TaskName PoisonZero |
- Windows nutzt einen Scheduled Task, keinen Windows-Dienst: Das Go-Binary lädt sein Modell beim ersten Start und würde das Start-Timeout des Service Control Managers verpassen.
- Ein Desktop-Notifier läuft in jeder Nutzersitzung für den Nutzer-Dialog: XDG-Autostart (Linux), LaunchAgent pro Nutzer (macOS), Run-Key-VBS-Wrapper (Windows).
Unbeaufsichtigte Installation (Intune / SCCM)
Setzen Sie den Installationsschlüssel in der Umgebung und führen Sie denselben Einzeiler aus; mit vorhandenem Code und ohne Terminal läuft er ohne Rückfragen:
bashUnbeaufsichtigt
PZ_ENROLL_CODE="ihr-code" \ sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"
powershellUnbeaufsichtigt
$env:PZ_ENROLL_CODE="ihr-code" irm https://poisonzero.com/install.ps1 | iex
Ergänzen Sie
PZ_DRY_RUN=1, um den aufgelösten Modus (fresh/re-enroll/upgrade) auszugeben und vor jeder Änderung zu beenden.Nur herunterladen und verifizieren
PZ_FETCH_ONLY=1 lädt das Binary, verifiziert seine SHA-256-Checksumme und schreibt es auf die Platte, ohne einen Dienst zu installieren (keine erhöhten Rechte):
bashNur laden
curl -fsSL https://poisonzero.com/install.sh | PZ_FETCH_ONLY=1 sh # schreibt ./poisonzero (überschreiben mit PZ_FETCH_DEST)
powershellNur laden
$env:PZ_FETCH_ONLY="1"; irm https://poisonzero.com/install.ps1 | iex # schreibt .\poisonzero.exe (überschreiben mit $env:PZ_FETCH_DEST)
Die Checksummen-Verifikation ist auf jedem Weg Pflicht; ein manipulierter oder abgeschnittener Download wird nie installiert.
Gerät prüfen
- Prüfen Sie mit dem Statusbefehl für Ihr OS (Tabelle oben), dass der Dienst läuft.
- Öffnen Sie die Konsole: Das enrollte Gerät erscheint mit seinem Status in Ihrer Geräteliste.
- Um ein Gerät auf einen frischen Installationsschlüssel umzustellen, führen Sie den Installer mit neuer
PZ_ENROLL_CODEerneut aus - es enrollt sauber neu.
Deinstallieren
Ein Befehl entfernt alles: zuerst die exec0-Datei managed-settings.d/50-poisonzero-exec0.json und die Claude-Code-Hooks aller Nutzer, dann Dienst, Programm und Datenverzeichnis. Lässt sich die exec0-Datei nicht entfernen, bricht die Deinstallation ab und das Programm bleibt installiert. Als Administrator (root) ausführen. Löschen Sie das Programm nie von Hand: Hooks, die auf ein fehlendes Programm zeigen, blockieren jeden Tool-Aufruf in Claude Code.
bashDeinstallieren
curl -fsSL https://poisonzero.com/install.sh | sudo sh -s -- --uninstall
powershellDeinstallieren
& ([scriptblock]::Create((irm https://poisonzero.com/install.ps1))) -Uninstall
bashDeinstallieren
# .deb / .rpm sudo apt remove poisonzero # oder: sudo dnf remove poisonzero # Homebrew poison0 remove-agent-integration && brew uninstall poisonzero # Scoop scoop uninstall poisonzero
Statt deinstallieren pausieren? Der Schutz ist von Grund auf fail-closed, das Entfernen des Dienstes ist also der saubere Weg, ihn ganz zu stoppen.
exec0-Hooks in Claude Code
exec0 hängt sich mit drei Hooks in Claude Code ein: UserPromptSubmit, PreToolUse und PostToolUse. Wo sie stehen, hängt von der Installationsart ab:
| Installation | Ort der exec0-Hooks |
|---|---|
| Systeminstallation: install.sh, install.ps1, .deb/.rpm (Programm in einem Ordner, den nur Administratoren ändern können) | Managed Settings von Claude Code, eigene Datei managed-settings.d/50-poisonzero-exec0.json |
| Benutzerinstallation: Homebrew unter einem Präfix des Benutzers, Scoop im Benutzerprofil | ~/.claude/settings.json des Benutzers |
| OS | Ordner der Managed Settings |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/ |
| Linux, WSL | /etc/claude-code/ |
| Windows | C:\Program Files\ClaudeCode\ |
- PoisonZero ändert nie Ihre
managed-settings.jsonund nie andere Dateien inmanaged-settings.d/. - Ordner, die PoisonZero anlegt, sind nur für Administratoren beschreibbar und für alle lesbar.
Wirkung
| Fall | Ergebnis |
|---|---|
Benutzer oder Agent entfernt den Eintrag oder setzt "disableAllHooks": true in Benutzer- oder Projekteinstellungen oder über --settings | Die exec0-Hooks laufen weiter. |
Sie setzen allowManagedHooksOnly | Die exec0-Hooks laufen weiter, Hooks aus Benutzer- und Projekteinstellungen nicht. |
Sie setzen "disableAllHooks": true in den Managed Settings | Die exec0-Hooks sind ebenfalls aus; poison0 doctor meldet das. |
| Gerät mit älterer Installation | Der Eintrag in ~/.claude/settings.json bleibt als Rückfall, bis der PoisonZero-Dienst sieht, dass Claude Code für diesen Benutzer den Managed-Eintrag aufruft. Dann entfernt der Dienst den Benutzereintrag. Laufen bis dahin beide, wird jeder Tool-Aufruf trotzdem nur einmal geprüft. |
Richtlinien schon zentral verteilt
Verteilen Sie Claude-Code-Richtlinien bereits über eine der folgenden Quellen, wendet Claude Code standardmäßig nur die höchste Quelle an und ignoriert 50-poisonzero-exec0.json:
| Quelle | Ort |
|---|---|
| Server-Managed Settings | Admin-Konsole von claude.ai |
| MDM-Profil (macOS) | Domain com.anthropic.claudecode |
| Gruppenrichtlinie oder Intune (Windows) | HKLM\SOFTWARE\Policies\ClaudeCode |
| Abhilfe | Weg |
|---|---|
| Quellen zusammenführen (Claude Code 2.1.242 oder neuer) | In der höchsten Quelle "managedSourcesBehavior": "merge" setzen. |
| Über die eigene Quelle verteilen | Inhalt von managed-settings.d/50-poisonzero-exec0.json von einem installierten Gerät in diese Quelle übernehmen. |
| Prüfen | poison0 doctor, poison0 exec0 status oder die PoisonZero-Konsole zeigen, ob Claude Code den Hook wirklich aufruft, und nennen die Quelle. |
exec0 für Claude Code aus- und einschalten
Braucht Administratorrechte. Unter Windows in einem Terminal als Administrator ausführen.
bashexec0 für Claude Code
# ausschalten sudo poison0 setup-claude --toolgate-off # einschalten sudo poison0 setup-claude --toolgate
powershellexec0 für Claude Code
# ausschalten poison0 setup-claude --toolgate-off # einschalten poison0 setup-claude --toolgate