Pi 1.0: como instalar o agente da Earendil e rodar isolado (macOS, Linux e Windows)

O Pi (earendil-works/pi) é um harness de agente minimalista e extensível, com licença MIT. A versão 1.0 saiu em 01/10/2026 (post oficial da Earendil) e traz Codemode com suporte nativo a MCP, carregamento adiado de ferramentas, modelos virtuais, cache warming para modelos da Anthropic, mensagens de sistema no meio da conversa, tema novo de TUI e tela cheia por padrão.

• 111.343 estrelas, 14.138 forks, MIT, último push em 01/10/2026 às 23:36 UTC (API do GitHub, 02/10/2026).
• Post no Hacker News: 953 pontos e 310 comentários (02/10/2026).
• O autor diz que "centenas de milhares de pessoas" usam o Pi toda semana. Essa é uma alegação do próprio autor, sem auditoria independente.
• O ponto de atenção: o Pi não tem sistema de permissão embutido. Por padrão ele roda com as permissões do usuário e do processo que o iniciou. O README manda isolar (Docker, Gondolin ou OpenShell) quando você precisa de limites mais fortes.

Fontes: post oficial earendil.com/posts/pi-1-0 (01/10/2026), README e docs do repositório earendil-works/pi, API do GitHub.

• Node.js 22.19 ou mais novo. Os instaladores de macOS, Linux e Windows podem instalar o Node se ele não estiver na máquina.
• Uma conta de provedor de modelo (assinatura ou chave de API). O Pi funciona com Claude, OpenAI e outros provedores.
• Docker, se você for seguir a seção de isolamento (recomendado antes do primeiro uso).

macOS e Linux

curl -fsSL https://pi.dev/install.sh | sh

Windows (PowerShell)

powershell -c "irm https://pi.dev/install.ps1 | iex"

Alternativa: npm

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

O Pi não precisa de lifecycle scripts de dependências em uma instalação normal; por isso o --ignore-scripts é seguro aqui.

Antes de rodar qualquer curl ... | sh: leia o script. É um instalador de terceiros executado com as suas permissões.

1. Abra um terminal dentro da pasta de um projeto de teste (não na sua pasta pessoal) e rode:

pi

1. Para conectar um provedor, rode /login dentro do Pi e escolha a assinatura ou a chave de API.
2. Dê uma tarefa em linguagem normal. Para rodar um comando de shell sem passar pelo modelo, use ! na frente (por exemplo, !pwd).
3. No Pi 1.0, o comando /session mostra o custo por modelo e o uso de cache.

O post também apresenta o Pi Durable, um pacote experimental para aplicações de agente de longa duração (npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord). Não é necessário para usar o Pi no terminal.

• pi abre a interface sem erro de comando não encontrado.
• Dentro do Pi, !pwd mostra a pasta que você escolheu (no Docker, deve mostrar /workspace).
• Depois de /login, uma tarefa simples recebe resposta do modelo.
• /session mostra o uso por modelo.

Segundo o README, o Pi não inclui um sistema de permissão para arquivos, processos, rede ou credenciais. A documentação oficial de containerization descreve quatro caminhos:

Opção 1: Docker simples (a mais direta)

Crie o arquivo 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"]

Monte a imagem:

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

Rode a partir da pasta que o Pi pode acessar:

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

Troque ANTHROPIC_API_KEY pela variável do seu provedor. Dentro do Pi, !pwd deve responder /workspace. Não monte o ~/.pi/agent do seu host a menos que queira expor ao container as credenciais, configurações e sessões do Pi.

Opção 2: Docker Sandboxes

Configure a credencial antes de criar o sandbox e não rode /login dentro dele (isso gravaria a credencial real no sandbox). Com chave de API da Anthropic:

sbx secret set anthropic

Depois, na pasta que será montada:

sbx run --kit "docker.io/sbx/pi-kit:latest" pi

Opção 3: OpenShell

openshell gateway add <gateway-url> --name <nome>
openshell gateway select <nome>
openshell sandbox create --name pi-sandbox --from pi -- pi

Num gateway remoto não existe bind mount da sua pasta: clone o repositório dentro do sandbox ou envie os arquivos com openshell sandbox upload pi-sandbox ./pasta /workspace.

Opção 4: Gondolin (ferramentas na micro-VM)

Requer Node.js 23.6 ou mais novo e QEMU instalado pelo gerenciador de pacotes do sistema. A partir de um checkout do código-fonte do Pi:

mkdir -p ~/.pi/agent/extensions
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts
cd /caminho/da/sua/pasta
pi -e ~/.pi/agent/extensions/gondolin

O Pi fica no host; as ferramentas read, write, edit, bash, grep, find e ls passam a rodar na micro-VM, com a sua pasta montada em /workspace.

• Versão do Node. O Pi exige Node.js 22.19+ e o Gondolin exige 23.6+.
• Credenciais dentro do container. Variáveis de ambiente passadas ao container ficam visíveis para tudo que roda nele. Passe só a chave do provedor necessária.
• Gondolin não é fronteira de credencial. Os comandos na VM herdam as variáveis de ambiente do host, então chaves em variáveis podem ficar visíveis lá dentro.
• Extensões fora da VM. No Gondolin, ferramentas de outras extensões continuam rodando no host, a menos que elas deleguem o trabalho.
• Escrita no host. Em /workspace montado com leitura e escrita, as mudanças chegam à sua pasta real. Use montagem somente leitura ou copie os arquivos se isso não for aceitável.
• /login no Docker Sandboxes. Não use: configure o segredo no host antes.

• O Pi não tem sistema de permissão embutido: sem isolamento, ele pode tudo que o seu usuário pode (arquivos, processos, rede, credenciais).
• O número de "centenas de milhares de usuários por semana" é do autor e não foi auditado.
• Este guia não traz benchmarks nem custos por modelo: o post oficial mostra o /session na demo, mas sem valores que possamos citar.
• Suporte do OpenShell a outros agentes além do Pi: não verificado aqui.
• Comandos e versões mudam rápido; confira o README e pi.dev antes de instalar.