pi-coding-agent Docker Harness

This repository provides a reproducible, secure, and user-transparent Docker environment (the cpi command) for running the pi coding agent with full project/workstation integration.

Features

• No files or config from user home are required except what you explicitly mount
• All session/config/secrets stay on host via explicit mounts (.pi/, .gitconfig, etc.)
• $HOME is a tmpfs RAM disk; no shell history, plugins or lingering files outside session
• UID/GID inside matches your host user, so there are no permission issues
• Starts interactive zsh with oh-my-zsh and plugins pre-installed in the image (no sshfs overhead)
• tmux available inside the container for pi sub-agent and background bash workflows
• Always shows a [cpi] indicator in the prompt when inside the container
• Fully resets/corrects terminal state on exit/kill, even on docker stop or crash
• Clean separation—never sources shell configs from host (all is container-local)
• Secure: no arbitrary code ever mounts from host except as :ro or with explicit opt-in

Usage

1. Build the image:

   docker build -t cpi:latest .

2. Install the wrapper script system-wide:

   sudo cp cpi /usr/local/bin/cpi

3. Use as a drop-in pi replacement (interactive, non-interactive, or scripted):

   cpi            # Interactive pi in container
   cpi -p "hello" # Print mode (no TUI)

Optional flags for mounts

• --home-dirs # Mounts $HOME/Documents and $HOME/Downloads in the container
• --parent-dir # Mounts one level up from $PWD as working dir

Environment

• Set OPENAI_API_KEY, OPENAI_BASE_URL before launching cpi (recommended for OpenAI proxies)
• .pi/ and .gitconfig are always mounted (for agent config and git identity)

Security

• No dynamic sourcing of host files or bashrcs—safe against shell injection or config leakage
• UID/GID maintained, no root
• Breaking terminal state after docker stop and other edge cases handled in script

Extension Points

• To further customize shell: edit entrypoint.sh where it writes the inline .zshrc

• To add packages permanently: edit the apk add block in Dockerfile

• To inject packages at build time without editing Dockerfile:

  docker build --build-arg EXTRA_PACKAGES="python3 py3-pip" -t cpi:latest .

For usage, contributing, and troubleshooting, see this repository’s README. For advanced pi agent configuration and workflows, consult the upstream pi-coding-agent documentation or visit pi.dev.

License

This project is licensed under the MIT License.