pi-docker

A minimal Docker wrapper for @mariozechner/pi-coding-agent so you can run pi against any local project without installing Node or the agent on your host. The docker image also includes python (and uv) for pi-agent to use.

Files

• Dockerfile — node:22-trixie-slim base, installs pi globally, pre-creates a world-writable /home/node/.pi so the container works under any UID.
• run.sh — runs the container against the current directory, mapped to /workspace, with ~/.pi mounted for persistent sessions/config.

Prerequisites

• Docker
• A directory at ~/.pi on the host (created automatically on first use; you can mkdir -p ~/.pi to be safe).

Build

docker build -t pi-docker .

Run

From the project directory you want pi to operate on use the below (or save it as an executable):

docker run --rm -it \
  --name pi-docker \
  -u $(id -u):$(id -g) \
  -w /workspace \
  -v "$PWD:/workspace" \
  -v "$HOME/.pi:/home/node/.pi" \
  pi-docker "$@" # or ghcr.io/samyoshua/pi-docker

• --rm -it — interactive, removed on exit.
• -u $(id -u):$(id -g) — runs as your host user so files created in /workspace aren't owned by root.
• -v "$PWD:/workspace" — mounts your current directory as the agent's workspace.
• -v "$HOME/.pi:/home/node/.pi" — persists pi sessions/config across runs on the host.

Notes

• The Dockerfile intentionally does not use USER node. Combined with --user $(id -u):$(id -g) at runtime, the container UID has no /etc/passwd entry, so HOME must point to a directory writable by any UID — hence the chmod -R 777 /home/node.
• If you change HOME in the Dockerfile, update the ~/.pi mount target in run.sh to match.

Troubleshooting

EACCES: permission denied, mkdir '/home/node/.pi/...' The host ~/.pi directory is owned by a different user than $(id -u). Fix with:

sudo chown -R "$(id -u):$(id -g)" ~/.pi

Or remove the -v "$HOME/.pi:/home/node/.pi" line in run.sh to use ephemeral in-container state.