Instalación y operación

Instalar el agente poison0: referencia completa

El agente poison0 es un pequeño daemon en cada dispositivo que vigila localmente los archivos de memoria de tus agentes. Esta página documenta el instalador de principio a fin: los comandos de instalación rápida, cada variable de entorno, el directorio de datos por sistema operativo, el servicio que ejecuta el daemon y cómo desplegarlo de forma desatendida.

~9 min de lectura · Instalación y operación

Resumen

Lo que hace el instalador, en orden:

Descarga el binario del daemon correspondiente desde https://poisonzero.com/dl/latest (Linux/macOS/Windows, amd64 o arm64).
Verifica su suma de comprobación SHA-256 contra el archivo SHA256SUMS publicado; aborta ante cualquier discrepancia.
Instala un servicio privilegiado y, opcionalmente, inscribe el dispositivo con una clave de instalación de la consola.

Instalar el servicio requiere permisos elevados: root (sudo) en Linux/macOS, una PowerShell de Administrador en Windows. Usa PZ_FETCH_ONLY=1 para solo descargar y verificar.

Requisitos comprobados antes de instalar:

x86-64: AVX2 (Intel Haswell/2013+, AMD Zen+).
ARM64: i8mm (Apple M2+; Apple M1 no compatible).
Windows: directorio de datos en un volumen NTFS.

Instalación rápida

Crea una clave de instalación en la consola (o usa un código heredado por dispositivo) y ejecuta el comando para tu plataforma:

bashTerminal

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

powershellPowerShell

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

Sin código predefinido: el instalador pide la clave de instalación (más las opciones de aceleración/nivel y headless en una terminal real); solo pide un app ID para el procedimiento heredado por dispositivo.
Una clave de instalación es de uso múltiple hasta su límite de canjes; un código heredado por dispositivo sigue siendo de un solo uso.
Ya inscrito y reejecutado sin código nuevo = actualización: reemplaza el binario, reinicia el servicio, conserva tus credenciales.

Las actualizaciones se ejecutan automáticamente. Instala una vez por dispositivo; reejecuta solo para cambiar la inscripción o forzar un reemplazo del binario.

Claves de instalación

Crea una clave de instalación en la consola, en Claves de instalación. Es la forma recomendada de enrolar dispositivos:

De uso múltiple: una clave enrola dispositivos hasta el límite de canjes que fijas al crearla; cada enrolamiento cuenta contra ese límite.
Se muestra una sola vez: cópiala al crearla - la consola no vuelve a mostrarla después.
Revocable: revócala en la consola para detener de inmediato más canjes; los dispositivos ya enrolados siguen funcionando.
Sin app ID necesario: el backend asigna a cada dispositivo su identidad en el momento del canje.

El procedimiento heredado, crear un dispositivo en la consola para obtener un app ID a juego y un código de un solo uso, sigue funcionando sin cambios. Úsalo para instaladores más antiguos o integraciones ya construidas en torno a él.

Variables de entorno

Fija cualquier opción mediante una variable de entorno para ejecutar la instalación de forma no interactiva:

Variable	Valores	Por defecto	Efecto
`PZ_ENROLL_CODE`	clave de instalación	ninguno	La clave de instalación de la consola. Requerida para un enrolamiento nuevo; sola basta, porque el backend asigna la identidad del dispositivo. Pasar una clave nueva en un dispositivo ya inscrito fuerza una reinscripción deliberada.
`PZ_APP_ID`	App ID	ninguno	Heredada y opcional: solo hace falta junto con un código por dispositivo más antiguo, generado antes de las claves de instalación. Se ignora sola.
`PZ_HEADLESS`	`none`, `standard`, `strict`	`none`	Fija la gestión de las solicitudes de confirmación del usuario en una máquina sin usuario de escritorio. `none` autodetecta a partir del usuario conectado; `standard`/`strict` escriben un archivo `headlessmode` que el daemon lee.
`PZ_BACKEND`	`cpu`, `gpu`	`cpu`	Backend de aceleración. Solo CPU es el valor por defecto recomendado y más seguro. La GPU es opcional y muestra un aviso de seguridad; el motor de GPU aún no está publicado.
`PZ_TIER`	`enterprise`, `ultra`	`enterprise`	Nivel de producto. `ultra` implica GPU y es fail-closed sin retorno a CPU; `enterprise` con GPU recae en una instalación de solo CPU que funciona.
`PZ_FETCH_ONLY`	`1`	sin definir	Solo descarga y verifica el binario, luego sale. No se instala ningún servicio, así que no hacen falta permisos elevados.
`PZ_FETCH_DEST`	ruta	`./poisonzero` (`.\poisonzero.exe` en Windows)	Ruta de destino del binario verificado cuando `PZ_FETCH_ONLY=1`.
`PZ_SETUP_AGENTS`	lista separada por comas, p. ej. `claude,codex`	sin definir	Conecta el comando local de estadísticas `/poisonzero` en los agentes indicados (Claude Code, Codex, Gemini, Cursor). Totalmente local, por adhesión.
`PZ_SETUP_STATUSLINE`	`1`	sin definir	Añade la línea de estado del agente poison0 en Claude Code (`~/.claude/settings.json`). Una línea de estado existente nunca se reemplaza.
`PZ_DRY_RUN`	`1`	sin definir	Imprime el modo resuelto (`fresh`/`re-enroll`/`upgrade`) y sale antes de cualquier efecto secundario. Útil para probar la automatización.
`POISONZERO_DATA_DIR`	ruta	valor por defecto según el SO (ver abajo)	Sobrescribe el directorio de datos que usan el daemon y el instalador.

Linux/macOS también aceptan una opción --headless none|standard|strict (gana sobre PZ_HEADLESS); el script de despliegue de Windows toma -Headless.

Directorio de datos y archivos

Binario: /usr/local/bin/poisonzero (Linux/macOS), <ProgramFiles>\PoisonZero\poisonzero.exe (Windows). Directorio de datos por SO:

SO	Directorio de datos	Propietario
Linux	`/var/lib/poisonzero` (archivo enroll en `/etc/poisonzero/enroll`)	`poisonzero:poisonzero`
macOS	`/Library/Application Support/PoisonZero`	`root:wheel`
Windows	`<ProgramData>\PoisonZero`	SYSTEM / Administradores

Archivos dentro del directorio de datos:

credentials - token almacenado del dispositivo; su presencia marca el dispositivo como inscrito y nunca se sobrescribe en una actualización.
enroll - entrada de inscripción de un solo uso (la clave de instalación, más appId en el procedimiento heredado) que consume poisonzero enroll en el primer arranque.
headlessmode - presente solo cuando se fijó standard/strict; ausente o vacío = autodetección.
vault/ - almacén de cuarentena para el contenido revertido.

Servicio / daemon

Se ejecuta como un servicio en segundo plano privilegiado, un mecanismo por SO:

SO	Tipo	Nombre y comando de estado
Linux	unidad systemd (root)	`poisonzero.service` · `systemctl status poisonzero`
macOS	LaunchDaemon de launchd	`com.poisonzero.daemon` · `launchctl print system/com.poisonzero.daemon`
Windows	Tarea programada (SYSTEM, al arrancar)	`PoisonZero` · `Get-ScheduledTask -TaskName PoisonZero`

Windows usa una tarea programada, no un servicio de Windows: el binario de Go carga su modelo en el primer arranque y perdería el tiempo de espera de arranque del Service Control Manager.
Un notificador de escritorio se ejecuta en cada sesión de usuario para la solicitud de confirmación del usuario: autoarranque XDG (Linux), LaunchAgent por usuario (macOS), envoltorio VBS vía clave Run (Windows).

Instalación desatendida (Intune / SCCM)

Define la clave de instalación en el entorno y luego ejecuta la misma línea; con el código presente y sin terminal, se ejecuta sin avisos:

bashDesatendida

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

powershellDesatendida

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

Añade PZ_DRY_RUN=1 para imprimir el modo resuelto (fresh/re-enroll/upgrade) y salir antes de cualquier cambio.

Solo descargar y verificar

PZ_FETCH_ONLY=1 descarga el binario, verifica su suma de comprobación SHA-256 y lo escribe en disco sin instalar un servicio (sin permisos elevados):

bashSolo descargar

curl -fsSL https://poisonzero.com/install.sh | PZ_FETCH_ONLY=1 sh
# escribe ./poisonzero (sobrescribir con PZ_FETCH_DEST)

powershellSolo descargar

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

La verificación de la suma de comprobación es obligatoria en cada ruta; una descarga manipulada o truncada nunca se instala.

Verificar el dispositivo

Comprueba que el servicio está en marcha con el comando de estado para tu SO (tabla de arriba).
Abre la consola: el dispositivo inscrito aparece con su estado en tu lista de dispositivos.
Para pasar un dispositivo a una clave de instalación nueva, reejecuta el instalador con una nueva PZ_ENROLL_CODE - se reinscribe limpiamente.

Desinstalar

Un solo comando lo elimina todo: primero el archivo de exec0 managed-settings.d/50-poisonzero-exec0.json y los hooks de Claude Code de todos los usuarios, después el servicio, el programa y el directorio de datos. Si el archivo de exec0 no se puede eliminar, la desinstalación se detiene y el programa sigue instalado. Ejecútalo como administrador (root). No borres nunca el programa a mano: los hooks que apuntan a un programa ausente bloquean cada llamada a herramienta de Claude Code.

bashDesinstalar

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

powershellDesinstalar

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

bashDesinstalar

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

¿Pausar en vez de desinstalar? La protección es fail-closed por diseño, así que quitar el servicio es la forma limpia de detenerla por completo.

Hooks de exec0 en Claude Code

exec0 se engancha a Claude Code con tres hooks: UserPromptSubmit, PreToolUse y PostToolUse. Dónde se registran depende del tipo de instalación:

Instalación	Ubicación de los hooks de exec0
Instalación de sistema: install.sh, install.ps1, .deb/.rpm (programa en una carpeta que solo los administradores pueden cambiar)	Managed settings de Claude Code, archivo propio `managed-settings.d/50-poisonzero-exec0.json`
Instalación de usuario: Homebrew en un prefijo del usuario, Scoop en el perfil del usuario	`~/.claude/settings.json` del usuario

SO	Carpeta de las managed settings
macOS	`/Library/Application Support/ClaudeCode/`
Linux, WSL	`/etc/claude-code/`
Windows	`C:\Program Files\ClaudeCode\`

PoisonZero nunca cambia tu managed-settings.json ni otros archivos de managed-settings.d/.
Las carpetas que crea PoisonZero solo las pueden escribir los administradores y las puede leer cualquiera.

Efecto

Caso	Resultado
Un usuario o agente elimina la entrada o pone `"disableAllHooks": true` en la configuración de usuario o de proyecto o con `--settings`	Los hooks de exec0 siguen funcionando.
Pones `allowManagedHooksOnly`	Los hooks de exec0 siguen funcionando; los de la configuración de usuario y de proyecto, no.
Pones `"disableAllHooks": true` en las managed settings	Los hooks de exec0 también quedan desactivados; `poison0 doctor` lo indica.
Equipo con una instalación anterior	La entrada en `~/.claude/settings.json` se queda como respaldo hasta que el servicio de PoisonZero ve que Claude Code llama a la entrada gestionada para ese usuario. Entonces el servicio elimina la entrada de usuario. Si hasta entonces funcionan las dos, cada llamada a herramienta se comprueba igualmente una sola vez.

Políticas ya distribuidas de forma central

Si ya distribuyes políticas de Claude Code por una de las siguientes fuentes, Claude Code aplica por defecto solo la fuente de mayor rango e ignora 50-poisonzero-exec0.json:

Fuente	Ubicación
Server-managed settings	Consola de administración de claude.ai
Perfil MDM (macOS)	Dominio `com.anthropic.claudecode`
Directiva de grupo o Intune (Windows)	`HKLM\SOFTWARE\Policies\ClaudeCode`

Solución	Cómo
Combinar las fuentes (Claude Code 2.1.242 o posterior)	Pon `"managedSourcesBehavior": "merge"` en la fuente de mayor rango.
Distribuir por tu propia fuente	Copia el contenido de `managed-settings.d/50-poisonzero-exec0.json` de un equipo instalado a esa fuente.
Comprobar	`poison0 doctor`, `poison0 exec0 status` o la consola de PoisonZero muestran si Claude Code llama de verdad al hook e indican la fuente.

Desactivar y activar exec0 para Claude Code

Requiere permisos de administrador. En Windows, ejecútalo en un terminal como administrador.

bashexec0 para Claude Code

# desactivar
sudo poison0 setup-claude --toolgate-off
# activar
sudo poison0 setup-claude --toolgate

powershellexec0 para Claude Code

# desactivar
poison0 setup-claude --toolgate-off
# activar
poison0 setup-claude --toolgate

Comentar este tema con una IA

Respuesta

Instalar el agente poison0: referencia completa

Resumen

Instalación rápida

Claves de instalación

Variables de entorno

Directorio de datos y archivos

Servicio / daemon

Instalación desatendida (Intune / SCCM)

Solo descargar y verificar

Verificar el dispositivo

Desinstalar

Hooks de exec0 en Claude Code

Efecto

Políticas ya distribuidas de forma central

Desactivar y activar exec0 para Claude Code

Instalar el agente poison0: referencia completa

Resumen

Instalación rápida

Claves de instalación

Variables de entorno

Directorio de datos y archivos

Servicio / daemon

Instalación desatendida (Intune / SCCM)

Solo descargar y verificar

Verificar el dispositivo

Desinstalar

Hooks de exec0 en Claude Code

Efecto

Políticas ya distribuidas de forma central

Desactivar y activar exec0 para Claude Code

Artículos relacionados