Instalar el agente poison0 en Linux
Instalar, desplegar, comprobar y quitar el agente poison0 en Linux.
Requisitos
| Requisito | Detalles |
|---|---|
| Procesador | x86-64 con AVX2 (Intel Haswell, 2013, o posterior, AMD Zen o posterior), o ARM64 con i8mm, por ejemplo AWS Graviton 3 o 4 y Ampere One. AWS Graviton 2 y Ampere Altra no son compatibles. |
| Kernel | Kernel 5.13 o posterior con Landlock activo, como en Ubuntu 22.04, Debian 12 y RHEL 9.6 o posterior. Si no, añada landlock al parámetro de arranque lsm=. |
| Contenedores | El perfil seccomp por defecto de Docker bloquea las llamadas al sistema de Landlock. Use un perfil adaptado. |
| Derechos | Derechos de root. El instalador se ejecuta mediante sudo. |
| Clave de instalación | Una clave de instalación de la consola, en Dispositivos → Despliegue varios dispositivos con una clave. |
| Agentes de IA | Al menos un agente de IA de Agentes compatibles. |
Instalar un equipo
Ejecute este comando en un terminal.
curl -fsSL https://poisonzero.com/install.sh | sudo PZ_ENROLL_CODE="<install-key>" sh
El instalador comprueba el programa con SHA256SUMS y se detiene si no coincide. Después instala el servicio y registra el equipo. Si el escritorio no tiene una herramienta de diálogo para las solicitudes de confirmación, intenta instalar zenity. En un terminal, el instalador pregunta si se envía el nombre del dispositivo a la consola. Usted responde Sí o No, no hay valor por defecto. Sí envía el hostname del equipo, No no envía ningún nombre. Con Ansible y scripts sin terminal no pregunta y no envía ningún nombre.
Para cambiar los valores por defecto, defina las variables de entorno de Referencia.
Comprobar el equipo
- Ejecute
systemctl status poisonzero. El servicio debe estar activo.journalctl -u poisonzeromuestra su registro. - Ejecute
poison0 doctoren su sesión de escritorio. Nombra lo que falla. - Abra la consola. El equipo aparece en Dispositivos.
poison0 también responde a p0 y pz. Si otro programa ya usa uno de estos nombres, ese alias se omite.
Tras la primera instalación, el modelo se descarga en segundo plano. Las reglas fijas protegen desde el principio.
Desplegar en muchos equipos
Use Ansible u otro script que se ejecute como root.
1. Instalar el agente
Sin terminal, pase la clave como variable de entorno. En un servidor sin escritorio, defina también PZ_HEADLESS.
PZ_ENROLL_CODE="<install-key>" sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"
2. Opcional: configurar /pz y la línea de estado
PoisonZero configura por sí mismo la protección de los agentes de IA tras la instalación, en cada cuenta de usuario y para todos los agentes compatibles. Si además quiere /pz y la línea de estado, ejecute estos comandos una vez en la cuenta de usuario. El segundo añade la línea de estado.
poison0 setup-claude poison0 setup-claude --statusline-only
Intune (Linux)
Intune ejecuta scripts Bash en Ubuntu Desktop 24.04 y 26.04 y en Red Hat Enterprise Linux 9 y 10. El equipo debe estar inscrito en Intune.
- En la consola abra Dispositivos, elija Descargar paquete de Intune y allí Linux. La consola descarga el script.
- En Intune, añada un script en Dispositivos → Scripts y correcciones → Scripts de plataforma → Agregar → Linux y cargue el archivo.
- Elija Root como contexto de ejecución. La frecuencia da igual; por defecto Intune ejecuta el script cada 15 minutos. En Reintentos indique por ejemplo 3.
- Asigne el script a un grupo de dispositivos.
El script no vuelve a registrar un equipo que ya está registrado. En la primera ejecución Intune puede pedir el consentimiento del usuario. El script contiene una clave de instalación que ven todos los administradores de Intune con acceso de lectura a los scripts. La consola la muestra como Intune Linux con la fecha. Vale un año; revóquela tras el despliegue.
Equipos privados: configuración firmada
Un equipo privado no recibe ajustes de la nube. Lee un client-config.json firmado.
- En la consola, abra el perfil y elija Exportar para privados.
- Pase el archivo al instalador con
PZ_CONFIG, como se muestra abajo. - O colóquelo con la tarea de Ansible que la consola muestra tras la exportación.
curl -fsSL https://poisonzero.com/install.sh | sudo \ PZ_ENROLL_CODE="<install-key>" PZ_CONFIG="./client-config.json" sh
El instalador comprueba el archivo con poison0 config verify y lo coloca en /etc/poisonzero/client-config.json, legible solo por root.
Actualización
Los dispositivos en la nube se actualizan solos. Para desactivarlo por dispositivo, use Settings → Protección y dispositivos → Actualizaciones en la consola. Los dispositivos privados no se actualizan solos.
Para actualizar a mano, vuelva a ejecutar el comando de instalación. Conserva las credenciales. Más en Actualizaciones y ciclo de vida.
A partir de esta versión, el archivo del programa es /usr/local/bin/poison0. poisonzero apunta a él y sigue funcionando, y las exclusiones de carpetas siguen siendo válidas. Para exclusiones de archivos o procesos, añada poison0 y mantenga poisonzero, porque los hooks de los agentes aún lo llaman.
Desinstalar
curl -fsSL https://poisonzero.com/install.sh | sudo sh -s -- --uninstall
La desinstalación quita primero los hooks de agente de todos los usuarios y se detiene si falla. Después quita el servicio, el notifier, los comandos, el programa y el directorio de datos.
Quite una instalación .deb o .rpm con el gestor de paquetes. Quita primero los hooks.
sudo apt remove poisonzero # .deb sudo dnf remove poisonzero # .rpm
Casos de cuarentena abiertos
La desinstalación lista cada caso de cuarentena abierto con su ruta original, la copia en cuarentena (*.infection.pz) y cómo restaurarlo. Una copia queda en /var/lib/poisonzero-quarantine, legible solo por root.
Ponga PZ_UNINSTALL_SKIP_QUARANTINE_COPY=1 para no guardar esa copia. Nada se restaura automáticamente. Revise cada archivo antes de restaurarlo.
La desinstalación descarta los cambios retenidos que aún esperan revisión. Para conservar uno, apruébelo antes: véalos con poison0 quarantine pending y ejecute poison0 quarantine pending approve <id>.
Solución de problemas
| Síntoma | Causa | Solución |
|---|---|---|
| El motor no arranca. | Landlock no está activo. | Active Landlock como se describe en Requisitos. |
poison0 doctor muestra que la descarga del modelo falló. | La descarga en segundo plano tras la primera instalación no terminó. | Ejecute sudo poison0 model para reintentarla ahora. poison0 doctor muestra el motivo. |
poison0 exec0 status muestra que Claude Code no llama al hook de exec0. | Los ajustes de Claude Code vienen de la consola de administración de claude.ai. Claude Code ignora entonces 50-poisonzero-exec0.json. | Ponga "managedSourcesBehavior": "merge" en esa fuente (Claude Code 2.1.242 o posterior), o copie allí el contenido del archivo. |
poison0 doctor informa de que los hooks gestionados están desactivados. | Los ajustes gestionados de Claude Code fijan "disableAllHooks": true. Esto desactiva también los hooks gestionados del agente. | Quite el ajuste donde está definido: en managed-settings.json, otro archivo de managed-settings.d/ o la consola de administración de claude.ai. El agente nunca cambia estas fuentes. |
| La instalación se detiene tras el registro y la configuración firmada no se coloca. | poison0 config verify rechazó client-config.json. Un archivo existente se mantiene. | Busque el código de salida en Referencia. |
| La desinstalación se detiene y no quita nada. | No pudo quitar los hooks de agente de todos los usuarios. | Ponga PZ_UNINSTALL_FORCE=1 y quite a mano las entradas restantes. |
Referencia
Variables de entorno
Defínalas antes de que arranque el instalador. Un flag, pasado tras sh -s --, tiene prioridad sobre su variable.
| Variable | Efecto |
|---|---|
PZ_ENROLL_CODE | La clave de instalación de la consola. En un equipo registrado, una clave nueva lo registra otra vez. |
PZ_APP_ID | Solo para un código de un solo uso que vino con un App ID. |
PZ_HEADLESS | Cómo se tratan las solicitudes de confirmación cuando ningún usuario de escritorio puede responder. none (por defecto) sigue al usuario conectado, standard trata siempre el equipo como sin escritorio, strict es el más estricto. Flag: --headless. |
PZ_DEVICE_NAME | El nombre del dispositivo en la consola, guardado en minúsculas, cifras y guiones, hasta 63 caracteres. El instalador muestra cómo se guarda el nombre. Las demás opciones se describen en el onboarding. |
PZ_SETUP_AGENTS | Añade el comando local de estadísticas /poison0 a los agentes indicados, por ejemplo claude,codex. |
PZ_SETUP_STATUSLINE | Ponga 1 para añadir la línea de estado a Claude Code. Una línea de estado existente se mantiene. |
PZ_SETUP_EXEC0 | Ponga off para mantener exec0 desactivado, también tras las actualizaciones. Los demás valores se ignoran. Actívelo en el perfil de la consola o con sudo poison0 exec0 observe o enforce. |
PZ_SETUP_LEAK0 | Solo dispositivos privados. Fija el modo de leak0: enforce, observe u off. Sin la variable y sin terminal, leak0 queda desactivado. |
PZ_BACKEND | cpu (por defecto) o gpu. El perfil de la consola decide si el equipo usa la GPU. |
PZ_TIER | enterprise (por defecto) o ultra. Con ultra, el instalador se detiene con un error. Fije por eso Ultra en el perfil de la consola. |
PZ_NO_SHORT_ALIAS | Ponga 1 para no crear el comando corto p0. |
PZ_FETCH_ONLY | Ponga 1 para solo descargar y comprobar el programa, sin servicio ni derechos de root. Va a ./poison0 o a PZ_FETCH_DEST. |
PZ_DRY_RUN | Ponga 1 para mostrar el modo de instalación y salir antes de cualquier cambio. |
POISONZERO_DATA_DIR | Cambia el directorio de datos del instalador y del agente. |
PZ_CONFIG | Ruta a un client-config.json firmado para un equipo privado. Flag: --config. |
PZ_QUARANTINE_RETENTION_DAYS | Solo dispositivos privados. Días que se guarda un caso de cuarentena, de 1 a 3650. Flag: --quarantine-retention-days. |
PZ_AUDIT_MAX_MB | Solo dispositivos privados. Tamaño en MB a partir del cual rota el registro de auditoría, de 1 a 1024. Flag: --audit-max-mb. |
Rutas y servicio
| Elemento | Ubicación |
|---|---|
| El programa y sus comandos. | /usr/local/bin/poison0. Los comandos poisonzero, p0 y pz apuntan a él. |
| El directorio de datos. | /var/lib/poisonzero, propietario poisonzero:poisonzero. Contiene las credenciales, los registros y la cuarentena. |
| El directorio de configuración. | /etc/poisonzero. Contiene el archivo enroll /etc/poisonzero/enroll y la configuración firmada. |
| El servicio. | La unidad systemd poisonzero.service. Arranca con el sistema y se ejecuta como root. |
| El notifier de las solicitudes de confirmación. | Arranca en cada sesión de escritorio mediante el autoarranque XDG, /etc/xdg/autostart/poisonzero-notifier.desktop. |
| El registro del servicio. | daemon.log en el directorio de datos, rota a los 5 MB. Las mismas líneas van al journal. |
| Los hooks de exec0 para Claude Code. | Una instalación de sistema (install.sh, .deb o .rpm) usa el archivo propio /etc/claude-code/managed-settings.d/50-poisonzero-exec0.json, también en WSL. Una instalación con Homebrew bajo un prefijo del usuario usa ~/.claude/settings.json en su lugar. |
Hooks de exec0 en Claude Code
El agente nunca cambia su managed-settings.json ni otros archivos de managed-settings.d/. Para desactivar o activar exec0 en Claude Code:
# turn off sudo poison0 setup-claude --toolgate-off # turn on sudo poison0 setup-claude --toolgate
Códigos de salida de la configuración firmada
poison0 config verify devuelve estos códigos. El instalador coloca el archivo solo con 0 o 6.
| Código de salida | Significado |
|---|---|
| 0 | El archivo es válido. |
| 6 | La licencia aún no está. El servicio comprueba el archivo al arrancar. |
| 1 | El archivo no se puede leer. |
| 3 | El archivo no está firmado para este dispositivo. |
| 4 | El archivo está desactualizado o caducado. |
| 5 | El archivo no es válido o es demasiado nuevo para esta versión del agente. |
| 7 | El equipo es un dispositivo en la nube, que ignora el archivo. |
Siga leyendo
Otros sistemas operativos: resumen de la instalación. Hardware: Requisitos del sistema. Aislamiento del motor: sandbox de Linux.