Skip to content

pi-container

pi-container

A containerized environment for running the pi-coding-agent with local LLM inference and full auditability. A transparent proxy container based on mitmproxy intercepts all HTTP/HTTPS/DNS traffic from the agent container, enforcing allowlisting and injecting secrets as needed. Supports macOS, Linux, and WSL2.

CI Coverage License: MIT Python: 3.14 uv

Highlights

  • Sandboxed agent — the agent container reaches the internet only through the proxy, on an --internal network with no gateway; every other protocol is denied by default.
  • Auditable traffic — all HTTP/HTTPS/DNS is intercepted by mitmproxy, with a hostname allowlist and a token redactor, and captured to a per-project flow export.
  • Local inference — llama.cpp's llama-server runs natively on the host (Metal / CUDA / ROCm), shared across projects by config fingerprint.
  • Per-workspace isolation — each workspace gets its own proxy, isolated network, mitmweb port, and config, seeded on first run.
  • Runtime-agnostic — works with Apple container, podman, and docker.

Quick start

cp .env.example .env       # then set ADMIN_PASSWORD to a strong value
./build.sh                 # build the proxy + agent images
alias pi="$PWD/run.sh"     # convenience 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 What's inside
Getting Started Prerequisites, hardware, platform notes, build & run
Architecture Components, network topology, egress policy, project structure
Configuration Environment variables and per-workspace config (allowlist, token replacer, tmpfs, apt deps, .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