Skills › Scientific Agent Skills › pi-agent › containerization.md

containerization.md

84 lines · skills/pi-agent/references/containerization.md at 5f2bc03

1# Containerization

3Source: https://pi.dev/docs/latest/containerization

5Reviewed against Pi 0.99.2 and the package versions listed in `../SKILL.md` on 2026-09-30.

7Pi runs with all permissions by default. Two general approaches: run the whole `pi` process inside an isolated environment, or run `pi` on the host and route tool execution into an isolated environment.

10|---|---|---|---|

15Extensions run wherever the `pi` process runs. If host Pi routes built-ins into a VM, other custom extension tools still run on the host unless they delegate too.

17The commands below follow Pi 0.99.2 documentation and are illustrative: Docker, Gondolin, and OpenShell runtimes were not started during this review.

Containerization

Source: https://pi.dev/docs/latest/containerization

Reviewed against Pi 0.99.2 and the package versions listed in ../SKILL.md on 2026-09-30.

Pi runs with all permissions by default. Two general approaches: run the whole pi process inside an isolated environment, or run pi on the host and route tool execution into an isolated environment.

Pattern	What is isolated	Best for	Notes
Gondolin extension	Built-in tools and `!` commands	Local micro-VM isolation while keeping auth on host	`examples/extensions/gondolin/`
Plain Docker	Whole `pi` process	Simplest local container boundary	Provider API keys enter the container
OpenShell	Whole `pi` process	Local or remote policy-controlled sandbox	Requires an OpenShell gateway

Extensions run wherever the pi process runs. If host Pi routes built-ins into a VM, other custom extension tools still run on the host unless they delegate too.

The commands below follow Pi 0.99.2 documentation and are illustrative: Docker, Gondolin, and OpenShell runtimes were not started during this review.

Raw lines 1 to 18

19## Gondolin

21[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.

23```bash

24cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin

25cd ~/.pi/agent/extensions/gondolin

26npm install --ignore-scripts

28cd /path/to/project

29pi -e ~/.pi/agent/extensions/gondolin

30```

32The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`. User `!` commands are routed into the VM as well, and file changes under `/workspace` write through to the host.

34Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU installed through your package manager.

Gondolin

Gondolin is a local Linux micro-VM.

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

The extension mounts the host cwd at /workspace in the VM and overrides read, write, edit, bash, grep, find, and ls. User ! commands are routed into the VM as well, and file changes under /workspace write through to the host.

Requirements: Node.js >= 23.6.0 for @earendil-works/gondolin, plus QEMU installed through your package manager.

Raw lines 19 to 35

36## Plain Docker

38`Dockerfile.pi`:

40```dockerfile

41FROM node:24-bookworm-slim

43RUN apt-get update \

44 && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \

45 && rm -rf /var/lib/apt/lists/*

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

48WORKDIR /workspace

49ENTRYPOINT ["pi"]

50```

52```bash

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

55docker run --rm -it \

56 -e ANTHROPIC_API_KEY \

57 -v "$PWD:/workspace" \

58 -v pi-agent-home:/root/.pi/agent \

59 pi-sandbox

60```

62`-v "$PWD:/workspace"` means reads and writes inside `/workspace` affect host files directly. Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions — mounting host `~/.pi/agent` exposes host auth and session files to the container.

Plain Docker

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" means reads and writes inside /workspace affect host files directly. Use a named volume for /root/.pi/agent if you want container-local settings and sessions — mounting host ~/.pi/agent exposes host auth and session files to the container.

Raw lines 36 to 63

64## OpenShell

66[NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) provides a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. It runs sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. Every sandbox requires an active gateway:

68```bash

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

70openshell gateway select <name>

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

73```

75The whole `pi` process runs inside the sandbox, so built-in tools, `!` commands, and extension tools all execute inside the boundary.

77Remote gateways do not bind-mount host project files, so sandbox writes are not reflected on your machine. Clone the repository inside the sandbox or transfer files explicitly:

79```bash

80openshell sandbox upload pi-sandbox ./repo /workspace

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

82```

84OpenShell providers can keep raw model API keys outside the sandbox: with inference routing configured, code inside the sandbox calls `https://inference.local` and the gateway injects provider credentials upstream. Point Pi at the corresponding OpenAI-compatible or Anthropic-compatible endpoint to use that route.

OpenShell

NVIDIA OpenShell provides a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. It runs sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. Every sandbox requires an active gateway:

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

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

The whole pi process runs inside the sandbox, so built-in tools, ! commands, and extension tools all execute inside the boundary.

Remote gateways do not bind-mount host project files, so sandbox writes are not reflected on your machine. Clone the repository inside the sandbox or transfer files explicitly:

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

OpenShell providers can keep raw model API keys outside the sandbox: with inference routing configured, code inside the sandbox calls https://inference.local and the gateway injects provider credentials upstream. Point Pi at the corresponding OpenAI-compatible or Anthropic-compatible endpoint to use that route.

Raw lines 64 to 84