컨테이너화

Pi는 기본적으로 모든 권한으로 실행되지만 경우에 따라 Pi이 쓸 수 있는 디렉터리와 액세스할 수 있는 디렉터리를 더 세밀하게 제어하고 싶을 수도 있습니다.

두 가지 일반 옵션이 있습니다. 다음 중 하나를 수행할 수 있습니다.

격리된 환경 내에서 전체 pi 프로세스를 실행하거나
호스트에서 pi를 실행하고 도구 실행을 격리된 환경으로 라우팅합니다.

패턴을 선택하세요

무늬	고립된 것은 무엇인가	다음에 가장 적합	메모
Gondolin 확장자	내장 도구 및 `!` 명령	호스트에서 인증을 유지하면서 로컬 마이크로 VM 격리	`examples/extensions/gondolin/`를 참조하세요.
일반 Docker	로컬 컨테이너의 전체 `pi` 프로세스	간단한 지역 격리	공급자 API key가 컨테이너에 들어갑니다.
OpenShell	정책에 따라 제어되는 sandbox의 전체 `pi` 프로세스	로컬 또는 원격 관리 sandbox	OpenShell 게이트웨이 필요

Extensions pi 프로세스가 실행되는 곳마다 실행됩니다. 도구 라우팅 확장을 사용하여 호스트 pi를 실행하는 경우 다른 사용자 정의 확장 도구가 작업을 위임하지 않는 한 호스트에서 계속 실행됩니다.

Gondolin

Gondolin은 로컬 Linux 마이크로 VM입니다. 호스트에서 pi를 원하지만 모든 내장 도구가 VM으로 라우팅되는 경우 example extension를 사용하세요.

설정:

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

마운트하려는 프로젝트에서 실행하십시오.

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

확장은 VM의 /workspace에 호스트 cwd를 마운트하고 read, write, edit, bash, grep, find 및 ls를 재정의합니다. 사용자 ! 명령도 VM으로 라우팅됩니다. /workspace 아래의 파일 변경 사항은 호스트에 기록됩니다.

요구 사항: @earendil-works/gondolin의 경우 Node.js >= 23.6.0 및 QEMU(패키지 관리자를 통한 설치 필요).

일반 Docker

가장 간단한 로컬 컨테이너 경계를 원할 경우 Docker에서 전체 pi 프로세스를 실행하세요.

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

빌드 및 실행:

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"는 현재 디렉터리를 /workspace의 컨테이너에 마운트하여 Docker 내부의 /workspace 읽기 및 쓰기가 Gondolin 예와 같이 호스트 파일에 직접 영향을 미치도록 합니다.

컨테이너-로컬 설정 및 세션을 원하는 경우 /root/.pi/agent에 명명된 볼륨을 사용하세요. 호스트를 마운트하면 ~/.pi/agent 호스트 인증 및 세션 파일이 컨테이너에 노출됩니다.

OpenShell

파일 시스템, 프로세스, 네트워크, 자격 증명 및 추론 제어를 통해 정책 제어 sandbox를 원할 경우 NVIDIA OpenShell를 사용하세요. OpenShell는 Docker가 지원하는 로컬 게이트웨이, Podman 또는 VM 런타임을 통해 또는 원격 Kubernetes 게이트웨이를 통해 sandboxes를 실행할 수 있습니다.

모든 sandbox에는 활성 게이트웨이가 필요합니다. sandbox을 만들기 전에 하나를 등록하고 선택하세요.

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

OpenShell sandbox 내부에서 pi 실행:

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

이 패턴에서는 전체 pi 프로세스가 sandbox 내부에서 실행됩니다. 내장 도구, ! 명령 및 확장 도구는 OpenShell 경계 내에서 실행됩니다.

게이트웨이가 원격인 경우 프로젝트 파일은 호스트에서 바인드 마운트되지 않습니다. 즉, sandbox에 쓴 내용이 컴퓨터에 반영되지 않습니다. sandbox 내부에 저장소를 복제하거나 OpenShell 파일 전송 명령을 사용하세요.

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

OpenShell 제공자는 sandbox 외부에 원시 모델 API key을 유지할 수 있습니다. 추론 라우팅이 구성되면 sandbox 내부의 코드가 https://inference.local를 호출할 수 있고 게이트웨이는 구성된 공급자 자격 증명 업스트림을 주입합니다. 모델 트래픽이 이 경로를 사용하도록 하려면 해당 OpenAI 호환 또는 Anthropic 호환 엔드포인트를 사용하도록 Pi를 구성하세요.