Pi Agent: Seguridad y confianza de proyectos
Pi Agent se ejecuta con los permisos de tu usuario actual.
Este capítulo presenta el mecanismo de confianza de proyectos, los límites de seguridad y las opciones de ejecución en contenedores.
Modelo de seguridad de Pi Agent
Pi Agent es unagente de codificación local—se ejecuta con los permisos del usuario con el que lo inicias, puede leer, escribir, editar archivos y ejecutar comandos de shell.
Esto significa:
- Puede acceder a todos los archivos a los que tu cuenta de usuario puede acceder.
- El alcance de los comandos que puede ejecutar es exactamente el mismo que si los ejecutaras manualmente en la terminal.
- elloNo incluyemecanismo de aislamiento de sandbox
Esto es un diseño intencional: Pi Agent necesita poder invocar las herramientas del proyecto, ejecutar pruebas e instalar dependencias, operaciones que requieren permisos reales del sistema.
La filosofía de diseño de Pi Agent es: no proporcionar un sandbox a medias que «parece seguro pero es fácil de malinterpretar».
El aislamiento real debe provenir de la capa del sistema operativo o de los límites de virtualización/contenedores.
Mecanismo de confianza de proyectos
La confianza de proyecto (Project Trust) controla si Pi Agent carga la configuración y las extensiones locales del proyecto.
No es un sandbox: solo controlaqué se carga al iniciar, no limita lo que el modelo puede hacer en la conversación.
¿Cuándo se activa la verificación de confianza?
Cuando Pi Agent detecta cualquiera de los siguientes elementos en el directorio del proyecto, se activa la verificación de confianza:
- .pi/settings.json (archivo de configuración del proyecto)
- .pi/extensions, .pi/skills, .pi/prompts, .pi/themes (directorios de recursos del proyecto)
- .pi/SYSTEM.md o .pi/APPEND_SYSTEM.md (prompts de sistema del proyecto)
- .agents/skills (directorio de Skills del proyecto)
Un directorio .pi vacío por sí solo no activa la verificación de confianza.
Proceso de decisión de confianza
Pi Agent decide si cargar los recursos del proyecto actual siguiendo un orden fijo.
- Comprueba si hay una decisión guardada en trust.json (buscando desde el directorio actual hacia arriba).
- Si existe, usa la decisión guardada.
- Si no existe, sigue el comportamiento de la configuración defaultProjectTrust (por defecto: ask, es decir, preguntar).
- Después de que el usuario toma una decisión, puede elegir «Recordar» y escribirla en trust.json.
Las decisiones de confianza se guardan por directorio en el archivo global ~/.pi/agent/trust.json.
Al buscar, se recorre hacia arriba por los directorios padre hasta coincidir con ese archivo; solo cuando no se encuentra ninguna decisión guardada se usa la lógica de defaultProjectTrust.
Al entrar por primera vez en un proyecto no confiable, la interfaz muestra la siguiente advertencia:
检测到项目本地配置 .pi/settings.json 是否信任此项目并加载其配置与扩展？(y/n/always/never)
El texto de la advertencia y las opciones pueden variar según la versión; prevalece la interfaz real.
La confianza de proyecto solo controla la carga de recursos protegidos, como extensiones, skills, etc.
Los archivos de contexto como AGENTS.md, CLAUDE.md se cargan siempre, independientemente de la confianza.
Configuración de defaultProjectTrust
Este ajuste determina la elección predeterminada de Pi Agent cuando no hay confirmación; el comportamiento difiere entre el modo interactivo y el no interactivo.
| Valor | Comportamiento en modo interactivo | Comportamiento en modo no interactivo |
|---|---|---|
| "ask" (por defecto) | Muestra un aviso de confirmación de confianza | No carga los recursos del proyecto (comportamiento igual que "never"). |
| "always" | Confiar automáticamente | Confiar automáticamente |
| "never" | Rechazar automáticamente | Rechazar automáticamente |
Método de configuración:
Ejemplo
"defaultProjectTrust": "always"
}
También puedes sobrescribir el comportamiento de una sola ejecución mediante parámetros de línea de comandos:
# 本次运行信任项目 $ pi --approve $ pi -a # 本次运行不信任项目 $ pi --no-approve $ pi -na
Guardar una decisión con el comando /trust
En el modo interactivo, puedes guardar en cualquier momento la decisión de confianza para el proyecto actual con el comando /trust:
/trust
Este comando escribe en~/.pi/agent/trust.json, que registra las decisiones de confianza guardadas por directorio.
/trust guarda la decisión actual, pero no recarga la sesión actual.
Si modificas la decisión de confianza, necesitas reiniciar Pi Agent para que el cambio surta efecto.
Consideraciones de seguridad en el modo no interactivo
En el modo Print (-p), el modo JSON (--mode json) y el modo RPC (--mode rpc), Pi Agent no muestra avisos de confianza.
En ese caso, el comportamiento depende completamente de la configuración defaultProjectTrust:
- Si se establece en "ask" o "never": los recursos del proyecto se ignoran.
- Si se establece en "always": los recursos del proyecto se cargan.
Puedes sobrescribir temporalmente este comportamiento con --approve o --no-approve.
Ejecutar código no confiable
Cuando necesites trabajar con repositorios no confiables o tareas automatizadas, se recomienda ejecutar Pi Agent en un contenedor o sandbox:
- Modo contenedor:ejecuta todo el proceso de pi en un contenedor Docker o en una máquina virtual (VM).
- Modo Gondolin:el host ejecuta pi y enruta la ejecución de herramientas a la micro VM de Gondolin.
- Modo OpenShell:todo el proceso de pi se ejecuta en el sandbox de control de políticas de NVIDIA, y se crean sandboxes a través de una puerta de enlace (gateway).
- Control de montajes:solo monta el directorio de trabajo al que el agente necesita acceder.
- Gestión de credenciales:evita montar el directorio ~/.pi/agent/ del host y proporciona una clave de API temporal con permisos mínimos.
- Aislamiento de red:si la tarea no necesita red, restringe el acceso de red del contenedor.
- Revisión de resultados:revisa los diff y los cambios antes de copiar la salida de vuelta a un sistema confiable.
Gondolin es un proyecto independiente de micro VM de código abierto (micro VM Linux local, requiere soporte de QEMU). Pi enruta la ejecución de sus herramientas integradas a través de una extensión de ejemplo.
OpenShell, a través deopenshell sandbox create --from picrea sandboxes; es necesario registrar y seleccionar primero una puerta de enlace.
El modo de puerta de enlace remota no hace bind-mount de directorios locales; es necesario usar comandos de subida y descarga para transferir archivos dentro y fuera del sandbox. Las credenciales del modelo pueden permanecer fuera del sandbox.
Si montas el directorio de trabajo del host en el contenedor en modo lectura-escritura, las operaciones de escritura dentro del contenedor seguirán afectando a los archivos del host.
Si necesitas una protección más estricta, usa montajes de solo lectura o copia los archivos hacia y desde el sandbox.
Consejos de seguridad
A continuación se ofrecen recomendaciones de seguridad según escenarios de uso comunes; revísalas antes de empezar.
| Escenario | Recomendación |
|---|---|
| Revisión de código de terceros | En un contenedor, con montaje de solo lectura. |
| CI/CD automatizado | Usar credenciales temporales y restringir la lista blanca de herramientas. |
| Configuración compartida por el equipo | Usar el .pi/settings.json del proyecto, pero sin incluir información sensible. |
| Instalar paquetes de extensiones de terceros | Revisar el código fuente antes de instalar; las extensiones pueden ejecutar código arbitrario. |
| Instalar Skills de terceros | Revisar el contenido de SKILL.md; los Skills pueden indicar al modelo que ejecute acciones arbitrarias. |