pi-container

A containerized environment for running the pi-coding-agent with local large language model (LLM) inference and full auditability. A transparent proxy container based on mitmproxy intercepts all HTTP, HTTPS, and DNS traffic from the agent container. It enforces an allowlist and injects secrets when required. It supports macOS, Linux, and WSL2.

Highlights

• Sandboxed agent — the agent container sends all internet traffic only through the proxy. It uses an --internal network without a gateway. The system denies all other protocols by default.
• Auditable traffic — all HTTP, HTTPS, and DNS traffic is intercepted by mitmproxy. It uses a hostname allowlist and a token injector. It saves the traffic to a flow export file for each project.
• Local inference — The llama-server tool from llama.cpp runs directly on the host computer (Metal / CUDA / ROCm). Multiple projects share it by using a configuration fingerprint.
• Per-workspace isolation — each workspace has its own pi-container image, proxy, isolated network, mitmweb port, and configuration. The system initializes these items on the first run.
• Rootless by construction — It runs on podman. The agent container runs inside a user namespace. The container root user maps to an unprivileged user on the host. On macOS or Windows, the podman machine requires at least 4 GB of memory (podman machine set --memory 4096); see Getting Started.

Quick start

cp .env.example .env       # then set ADMIN_PASSWORD to a complex value
./build.sh                 # build the proxy, toolchain and agent images
alias pi="$PWD/run.sh"     # useful alias
cd /path/to/your/project   # any workspace
pi                         # launch the agent for that workspace

See Getting Started for prerequisites, hardware requirements, and platform-specific notes.

Documentation

Page	Contents
Getting Started	Prerequisites, hardware, platform notes, build & run
Architecture	Components, network topology, egress policy, project structure
Configuration	Environment variables and per-workspace configuration (allowlist, token replacer, temporary file system, apt dependencies, .gitignore)
Development	Local dev setup, tests, lint, coverage
Releases	Branch strategy, versioning, and release process
Proxy & addons	Transparent proxy operation, CA cert, and the allowlist / token replacer / flow export addons + addon development guide

License

MIT

Agentic coding disclosure

Built using agentic coding tools.

• Pi Coding Agent via pi-container for agentic coding.
• Claude Code