AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

pi-agent

Builds with and operates Pi, the minimal terminal coding harness. Use for installing Pi, configuring providers/models/settings/environment variables, creating Pi skills/extensions/packages/themes/prompt templates, embedding Pi through the SDK, integrating over RPC or JSON event streams, parsing sessions, running local models through the llama.cpp router, developing custom Pi providers and TUI components, or using ecosystem packages such as pi-subagents (delegation/orchestration), pi-mcp-adapter (MCP servers), pi-interview (interactive forms), and pi-web-access (web search, fetching, video understanding).

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--pi-agent at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 36

references/containerization.md

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.

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.

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.

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.