Contenedorización

Pi se ejecuta con todos los permisos de forma predeterminada, pero en algunos casos querrás tener más control sobre en qué directorios Pi puede escribir y qué accesos tiene.

Hay dos opciones generales. Tú puedes

1. ejecutar todo el proceso pi dentro de un entorno aislado, o
2. ejecute pi en el host y enrute la ejecución de la herramienta a un entorno aislado.

Extensions se ejecuta dondequiera que se ejecute el proceso pi. Si ejecuta el host pi con una extensión de enrutamiento de herramientas, otras herramientas de extensión personalizadas aún se ejecutan en el host a menos que también deleguen sus operaciones.

Gondolin es una micro-VM Linux local. Utilice example extension cuando desee pi en el host, pero todas las herramientas integradas se dirigen a la VM.

Configuración:

cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts

Ejecute desde el proyecto que desea montar:

cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin

La extensión monta el host cwd en /workspace en la VM y anula read, write, edit, bash, grep, find y ls. Los comandos del usuario ! también se enrutan a la VM. Los cambios de archivos en /workspace se escriben en el host.

Requisitos: Node.js >= 23.6.0 para @earendil-works/gondolin, más QEMU (requiere instalación a través de su administrador de paquetes).

Ejecute todo el proceso pi en Docker cuando desee el límite de contenedor local más simple.

Dockerfile.pi:

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

Construir y ejecutar:

docker build -t pi-sandbox -f Dockerfile.pi .

docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

El -v "$PWD:/workspace" monta su directorio actual en el contenedor en /workspace de modo que las lecturas y escrituras en /workspace dentro de Docker afecten directamente a sus archivos host, como en el ejemplo Gondolin.

Utilice un volumen con nombre para /root/.pi/agent si desea configuraciones y sesiones locales de contenedor. Al montar su host ~/.pi/agent se exponen los archivos de sesión y autenticación del host en el contenedor.

Utilice NVIDIA OpenShell cuando desee un sandbox controlado por políticas con controles de sistema de archivos, procesos, redes, credenciales y de inferencia. OpenShell puede ejecutar sandboxes a través de una puerta de enlace local respaldada por Docker, Podman o un tiempo de ejecución de VM, o mediante una puerta de enlace remota de Kubernetes.

Cada sandbox requiere una puerta de enlace activa. Regístrese y seleccione uno antes de crear un sandbox:

openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>

Lanza pi dentro de un OpenShell sandbox:

openshell sandbox create --name pi-sandbox --from pi -- pi

En este patrón, todo el proceso pi se ejecuta dentro del sandbox. Las herramientas integradas, los comandos ! y las herramientas de extensión se ejecutan dentro del límite OpenShell.

Si la puerta de enlace es remota, los archivos del proyecto no se montan enlazados desde el host, lo que significa que las escrituras en sandbox no se reflejan en su máquina. Clona el repositorio dentro de sandbox o usa los comandos de transferencia de archivos OpenShell:

openshell sandbox upload pi-sandbox ./repo /workspace
openshell sandbox download pi-sandbox /workspace/repo ./repo-out

Los proveedores de OpenShell pueden mantener los modelos sin procesar API key fuera de sandbox. Cuando se configura el enrutamiento de inferencia, el código dentro de sandbox puede llamar a https://inference.local y la puerta de enlace inyecta las credenciales del proveedor configurado en sentido ascendente. Configure Pi para usar el punto final correspondiente compatible con OpenAI o Anthropic si desea que el tráfico modelo use esta ruta.