pi-devbox/DOCKER_HUB.md

pi-devbox

A self-contained Docker container for the pi coding-agent — pi + companion repos + MemPalace + a curated set of dev tooling, ready to run.

Current :latest ships pi {{PI_VERSION}} (resolved at build time; see Versioning).

Image variants

Tag	Architectures	Size (compressed)	What you get
joakimp/pi-devbox:latest	amd64, arm64	~1.1 GB	Self-contained: base + pi {{PI_VERSION}} + companions
joakimp/pi-devbox:vX.Y.Z	amd64, arm64	same	Pinned semver release
joakimp/pi-devbox:latest-studio	amd64, arm64	~1.15 GB	latest + pi-studio: browser prompt editor, KaTeX/Mermaid preview, tmux-backed literate REPLs
joakimp/pi-devbox:vX.Y.Z-studio	amd64, arm64	same	Pinned semver studio release
joakimp/pi-devbox:base-latest	amd64, arm64	~1.0 GB	Base layer alias (internal building block; pull :latest instead)
joakimp/pi-devbox:base-<hash>	amd64, arm64	~1.0 GB	Content-addressed base; immutable. Stable parent for variant rebuilds.

pi-studio (-studio tags): launch with /studio --no-browser --port 8765 inside a pi session. The server binds 127.0.0.1 inside the container, so reach it via host networking or a loopback bridge (and ssh -L for a remote host; mosh needs a parallel ssh -L). Full recipe: README → Using pi-studio.

Quick start

One-shot, no persistence:

docker run -it --rm \
  -v "$PWD":/workspace \
  -v "$HOME/.ssh":/home/developer/.ssh:ro \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  joakimp/pi-devbox:latest pi

For a fully-configured environment with persistent settings, MemPalace memory, neovim plugins, and shell history surviving container recreation, use docker-compose. You don't need to clone the repo — just grab two template files:

mkdir -p ~/pi-devbox && cd ~/pi-devbox
curl -O https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/docker-compose.yml
curl -fsSL https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/.env.example -o .env
# Edit .env — set WORKSPACE_PATH, an LLM API key (ANTHROPIC_API_KEY,
# OPENAI_API_KEY, GEMINI_API_KEY, or AWS_*), and your git identity.
docker compose run --rm devbox pi

Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini, AWS Bedrock SSO + static), persistence model, configuration reference, build args, troubleshooting: https://gitea.jordbo.se/joakimp/pi-devbox#readme

What's inside

pi and companions

• pi {{PI_VERSION}} (@earendil-works/pi-coding-agent) — installed at /usr/bin/pi
• pi-toolkit — keybindings (mosh/tmux-friendly Shift+Enter, Ctrl+J, Alt+J newline bindings), AWS env loader, settings template
• pi-extensions — 7 user-facing extensions: ext-toggle, mcp-loader, todo, ssh-controlmaster, notify, git-checkpoint, confirm-destructive
• fork (pi-fork) and recall (pi-observational-memory) tools
• mempalace bridge — MCP extension auto-symlinked so pi reads/writes the host-mounted palace
• image-baked agent skills — skills under /usr/local/share/pi-devbox/skills/ (e.g. pi-devbox-environment, which teaches agents the container's persistence/networking/DNS/tmux/REPL specifics) are symlinked into ~/.agents/skills/ on start, available with or without a mounted skillset repo

The entrypoint deploys/registers all of these on first container start. Re-running is idempotent and preserves user edits.

MemPalace (persistent agent memory)

• MemPalace + MCP server — semantic search over conversation history, knowledge graph, diary; queryable via 29 mempalace_* tools inside pi
• ChromaDB ONNX embedding model pre-warmed at build time (all-MiniLM-L6-v2)
• Bind-mount your host's ~/.mempalace and the host-pi and container-pi share one brain

Document and image tooling

• pandoc — universal Markdown↔HTML/Org/RST/etc. conversion. Useful well beyond pi: agent-driven doc exports, format conversion, etc.
• graphviz (dot) — diagram rendering pipelines
• imagemagick (magick) — image conversion / resizing

Modern CLI tooling

• Editor: neovim (LazyVim defaults), tmux (configured for 0-indexed sessions)
• Search/nav: ripgrep, fd, fzf, zoxide
• Display: bat, eza, htop, tree
• Data: jq, yq
• Help: tldr (tealdeer — Rust port; run tldr --update once to populate cache)
• Git: git-lfs, git-crypt, gitleaks (for pre-commit secret scanning)
• Build: gcc, g++, make, patch
• Misc: gosu, age, rsync, less

Language toolchains

• Python: system Python 3 + uv (preferred) for fast Python package management. Run any Python REPL/notebook stack on demand without bloating the image:

  uv run --with ipython ipython
  uv run --with jupyterlab jupyter lab --no-browser --port 8888
  uv run --with marimo marimo edit
  

• Node.js v22 + npm (used by pi itself)
• Rust — rustup-init is on PATH; install toolchains on demand
• Go — opt-in via --build-arg INSTALL_GO=true if rebuilding from source

Cloud + secrets

• AWS CLI v2 — for SSO + Bedrock auth (pi's preferred LLM provider for the maintainer's setup)
• Gitea MCP server — for Gitea API access from inside pi
• age, git-crypt — encryption tooling

SSH and networking

• OpenSSH client with ControlMaster auto preconfigured on a writable socket path (/tmp/sshcm/). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps). A read-only ~/.ssh carrying a per-host ControlPath (common CGNAT configs) is handled too — redirected to a writable socket dir for both pi --ssh and dssh/dscp.
• A LAN-access helper that auto-configures ssh jump-via-host on VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container can reach the host's directly-attached LAN peers (dssh <peer> alias; DEVBOX_LAN_ACCESS / HOST_SSH_USER).

Versioning

From v1.0.0 onward, pi-devbox uses semver:

• Major — architectural changes. v1.0.0 is the first decoupled release, where pi-devbox got its own self-contained build chain (previously it was a thin re-brand of opencode-devbox's pi-only variant).
• Minor — new image variants, significant base additions.
• Patch — pi version bumps, smaller fixes.

The pi binary version inside any given release is shown in this description (currently {{PI_VERSION}} for :latest) and asserted by smoke tests to match what's documented — version drift is caught at CI time, not on user pull.

Pre-v1.0.0 history. Tags v0.74.0…v0.79.0 followed the pi npm version directly (v{pi_version}[letter]). Those images remain on Hub but are deprecated in favor of :latest / :v1.X.Y. The legacy :base-pi-only* tags were CI artifacts of the old opencode-devbox-based build pipeline; they will be removed in a future opencode-devbox v2.0.0.

Build pipeline

pi-devbox is built in two phases:

1. Base (Dockerfile.base) → base-<hash> tag, content-addressed over Dockerfile.base + rootfs/ + entrypoint*.sh. Rebuilt only when those change.
2. Variant (Dockerfile.variant) → :latest and :vX.Y.Z. FROMs the base, adds the pi install + companions.

base-latest is an alias of the most recent base.

Persistent state

User edits and pi-installed packages survive container recreation when you mount these named volumes. Use the included docker-compose.yml and they're set up automatically.

Volume	Mount point	What it holds
devbox-pi-config	/home/developer/.pi/	pi settings, extension toggles, sessions, user-installed pi packages (npm install -g, pi install npm:…)
devbox-shell-history	/home/developer/.cache/bash	bash history
devbox-zoxide	/home/developer/.local/share/zoxide	zoxide directory jump database
devbox-nvim-data	/home/developer/.local/share/nvim	neovim plugin & Mason package state
devbox-uv	/home/developer/.local/share/uv	uv Python installs and tool cache
devbox-ssh-local	/home/developer/.ssh-local	LAN-jump key (one-time host authorization survives recreate)

Optional volumes for MemPalace (commented out by default — uncomment in docker-compose.yml to persist conversation memory across restarts):

Volume	Mount point	What it holds
devbox-palace	/home/developer/.mempalace	palace data (drawers, knowledge graph, embeddings)
devbox-chroma-cache	/home/developer/.cache/chroma	ChromaDB embedding model cache (~80 MB, can be rebuilt)

User-installed pi packages

NPM_CONFIG_PREFIX is set inside the container to /home/developer/.pi/npm-global. Anything you pi install npm:<pkg> or npm install -g lands on the devbox-pi-config named volume — survives container recreation and image rebuilds. A user-installed pi wins over the baked one via PATH order, so you can pin a different pi version without rebuilding the image.

Source

• This image: https://gitea.jordbo.se/joakimp/pi-devbox
• pi: https://github.com/earendil-works/pi
• pi-toolkit: https://gitea.jordbo.se/joakimp/pi-toolkit
• pi-extensions: https://gitea.jordbo.se/joakimp/pi-extensions
• MemPalace: https://github.com/MemPalace/mempalace

License

MIT (the image; pi and the bundled tools each carry their own licenses). See LICENSE and THIRD_PARTY.md in the source repo.