Comentar este tema con una IA

Obtiene una respuesta de la documentación y la página de la que procede.

Instalación y operación

Instalar el agente poison0 en Linux

Instalar, desplegar, comprobar y quitar el agente poison0 en Linux.

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

Requisitos

RequisitoDetalles
Procesadorx86-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.
KernelKernel 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=.
ContenedoresEl perfil seccomp por defecto de Docker bloquea las llamadas al sistema de Landlock. Use un perfil adaptado.
DerechosDerechos de root. El instalador se ejecuta mediante sudo.
Clave de instalaciónUna clave de instalación de la consola, en Dispositivos → Despliegue varios dispositivos con una clave.
Agentes de IAAl menos un agente de IA de Agentes compatibles.

Instalar un equipo

Ejecute este comando en un terminal.

bashTerminal
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

  1. Ejecute systemctl status poisonzero. El servicio debe estar activo. journalctl -u poisonzero muestra su registro.
  2. Ejecute poison0 doctor en su sesión de escritorio. Nombra lo que falla.
  3. 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.

bashComo root
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.

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

  1. En la consola abra Dispositivos, elija Descargar paquete de Intune y allí Linux. La consola descarga el script.
  2. En Intune, añada un script en Dispositivos → Scripts y correcciones → Scripts de plataforma → Agregar → Linux y cargue el archivo.
  3. 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.
  4. 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.

  1. En la consola, abra el perfil y elija Exportar para privados.
  2. Pase el archivo al instalador con PZ_CONFIG, como se muestra abajo.
  3. O colóquelo con la tarea de Ansible que la consola muestra tras la exportación.
bashTerminal
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

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

bashPaquetes
sudo apt remove poisonzero   # .deb
sudo dnf remove poisonzero   # .rpm
No borre el programa a mano. Los hooks de Claude Code que apuntan a un programa ausente bloquean cada llamada a herramienta.

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íntomaCausaSolució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.

VariableEfecto
PZ_ENROLL_CODELa clave de instalación de la consola. En un equipo registrado, una clave nueva lo registra otra vez.
PZ_APP_IDSolo para un código de un solo uso que vino con un App ID.
PZ_HEADLESSCó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_NAMEEl 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_AGENTSAñade el comando local de estadísticas /poison0 a los agentes indicados, por ejemplo claude,codex.
PZ_SETUP_STATUSLINEPonga 1 para añadir la línea de estado a Claude Code. Una línea de estado existente se mantiene.
PZ_SETUP_EXEC0Ponga 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_LEAK0Solo dispositivos privados. Fija el modo de leak0: enforce, observe u off. Sin la variable y sin terminal, leak0 queda desactivado.
PZ_BACKENDcpu (por defecto) o gpu. El perfil de la consola decide si el equipo usa la GPU.
PZ_TIERenterprise (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_ALIASPonga 1 para no crear el comando corto p0.
PZ_FETCH_ONLYPonga 1 para solo descargar y comprobar el programa, sin servicio ni derechos de root. Va a ./poison0 o a PZ_FETCH_DEST.
PZ_DRY_RUNPonga 1 para mostrar el modo de instalación y salir antes de cualquier cambio.
POISONZERO_DATA_DIRCambia el directorio de datos del instalador y del agente.
PZ_CONFIGRuta a un client-config.json firmado para un equipo privado. Flag: --config.
PZ_QUARANTINE_RETENTION_DAYSSolo dispositivos privados. Días que se guarda un caso de cuarentena, de 1 a 3650. Flag: --quarantine-retention-days.
PZ_AUDIT_MAX_MBSolo 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

ElementoUbicació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:

bashexec0 para 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 salidaSignificado
0El archivo es válido.
6La licencia aún no está. El servicio comprueba el archivo al arrancar.
1El archivo no se puede leer.
3El archivo no está firmado para este dispositivo.
4El archivo está desactualizado o caducado.
5El archivo no es válido o es demasiado nuevo para esta versión del agente.
7El 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.