Conteinerização

Pi é executado com todas as permissões por padrão, mas em alguns casos, você desejará ter mais controle sobre quais diretórios Pi podem gravar e quais acessos ele possui.

Existem duas opções gerais. Você pode

1. execute todo o processo pi dentro de um ambiente isolado, ou
2. execute pi no host e roteie a execução da ferramenta para um ambiente isolado.

Extensions é executado onde quer que o processo pi seja executado. Se você executar o host pi com uma extensão de roteamento de ferramentas, outras ferramentas de extensão customizadas ainda serão executadas no host, a menos que também deleguem suas operações.

Gondolin é uma micro-VM Linux local. Use example extension quando quiser pi no host, mas todas as ferramentas integradas roteadas para a VM.

Configurar:

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

Execute a partir do projeto que você deseja montar:

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

A extensão monta o host cwd em /workspace na VM e substitui read, write, edit, bash, grep, find e ls. Os comandos do usuário ! também são roteados para a VM. As alterações do arquivo em /workspace são gravadas no host.

Requisitos: Node.js >= 23.6.0 para @earendil-works/gondolin, mais QEMU (requer instalação através do seu gerenciador de pacotes).

Execute todo o processo pi em Docker quando desejar o limite de contêiner local mais simples.

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"]

Construa e execute:

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

O -v "$PWD:/workspace" monta seu diretório atual no contêiner em /workspace de forma que leituras e gravações em /workspace dentro de Docker afetem diretamente seus arquivos host, como no exemplo Gondolin.

Use um volume nomeado para /root/.pi/agent se desejar configurações e sessões locais do contêiner. Montar seu host ~/.pi/agent expõe a autenticação do host e os arquivos de sessão ao contêiner.

Use NVIDIA OpenShell quando desejar um sandbox controlado por política com sistemas de arquivos, processos, rede, credenciais e controles de inferência. OpenShell pode executar sandboxes por meio de um gateway local apoiado por Docker, Podman ou um tempo de execução de VM, ou por meio de um gateway Kubernetes remoto.

Cada sandbox requer um gateway ativo. Registre-se e selecione um antes de criar um sandbox:

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

Inicie pi dentro de um OpenShell sandbox:

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

Neste padrão, todo o processo pi é executado dentro de sandbox. Ferramentas integradas, comandos ! e ferramentas de extensão são executadas dentro do limite OpenShell.

Se o gateway for remoto, os arquivos do projeto não serão montados por ligação a partir do host, o que significa que as gravações em sandbox não serão refletidas em sua máquina. Clone o repositório dentro de sandbox ou use comandos de transferência de arquivo OpenShell:

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

Os provedores OpenShell podem manter o modelo bruto API keys fora do sandbox. Quando o roteamento de inferência é configurado, o código dentro de sandbox pode chamar https://inference.local e o gateway injeta as credenciais do provedor configuradas upstream. Configure Pi para usar o endpoint compatível com OpenAI ou Anthropic correspondente se desejar que o tráfego do modelo use esta rota.