Contenedorización

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

Hay dos opciones generales. Puedes:

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

Elegir un patrón

Patrón	Qué se aísla	Ideal para	Notas
Extensión Gondolin	Herramientas integradas y comandos !	Aislamiento local en micro-VM manteniendo auth en el host	Ver examples/extensions/gondolin/.
Docker simple	Todo el proceso pi en un contenedor local	Aislamiento local sencillo	Las claves API del provider entran al contenedor.
OpenShell	Todo el proceso pi en un sandbox controlado por políticas	Sandbox local o remoto gestionado	Requiere una puerta de enlace OpenShell

Las extensiones se ejecutan donde corre el proceso pi. Si ejecutas pi en el host con una extensión de enrutamiento de herramientas, otras herramientas de extensión personalizadas siguen ejecutándose en el host a menos que también deleguen sus operaciones.

Gondolin

Gondolin es una micro-VM Linux local. Usa la extensión de ejemplo cuando quieras pi en el host pero todas las herramientas integradas enrutadas 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

Ejecuta desde el proyecto que quieras montar:

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

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

Requisitos: Node.js >= 23.6.0 para @earendil-works/gondolin, más QEMU (requiere instalación mediante tu gestor de paquetes).

Docker simple

Ejecuta todo el proceso pi en Docker cuando quieras 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

-v "$PWD:/workspace" monta tu directorio actual en el contenedor en /workspace de modo que las lecturas y escrituras en /workspace dentro de Docker afectan directamente tus archivos del host, como en el ejemplo Gondolin.

Usa un volumen con nombre para /root/.pi/agent si quieres ajustes y sesiones locales del contenedor. Montar tu ~/.pi/agent del host expone archivos de auth y sesión del host al contenedor.

OpenShell

Usa NVIDIA OpenShell cuando quieras un sandbox controlado por políticas con controles de sistema de archivos, procesos, red, credenciales e inferencia. OpenShell puede ejecutar sandboxes a través de una puerta de enlace local respaldada por Docker, Podman o un runtime de VM, o a través de una puerta de enlace Kubernetes remota.

Cada sandbox requiere una puerta de enlace activa. Regístrala y selecciónala antes de crear un sandbox:

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

Lanza pi dentro de un sandbox OpenShell:

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, comandos ! y 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 desde el host, lo que significa que las escrituras en el sandbox no se reflejan en tu máquina. Clona el repositorio dentro del sandbox o usa comandos de transferencia de archivos de OpenShell:

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

Los providers de OpenShell pueden mantener las claves API del modelo fuera del sandbox. Cuando el enrutamiento de inferencia está configurado, el código dentro del sandbox puede llamar a https://inference.local, y la puerta de enlace inyecta las credenciales del provider configuradas upstream. Configura Pi para usar el endpoint compatible con OpenAI o Anthropic correspondiente si quieres que el tráfico del modelo use esta ruta.