pi-devbox/DOCKER_HUB.md

pi-devbox

A Docker container with pi coding-agent pre-installed, built on top of opencode-devbox's base image. Pi gets a fully-loaded development environment in one docker run.

Image variants

Tag	Size (compressed)	What you get
joakimp/pi-devbox:latest	~700 MB	Pi + companion repos, on top of the opencode-devbox base
joakimp/pi-devbox:vX.Y.Z	same	Pinned pi version (tracks the pi npm package version)

Multi-arch: linux/amd64, linux/arm64.

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-devbox is a re-brand of the pi-only build — it builds FROM joakimp/pi-devbox:base-pi-only and adds no layers of its own. That building-block tag is produced by opencode-devbox's CI (from Dockerfile.variant with INSTALL_OPENCODE=false) but published here, in the pi-devbox repo, so an opencode-devbox tag never ships without opencode. The pi-only build is lean and pi-focused (no opencode — use opencode-devbox:latest-with-pi if you want both). Everything below is inherited from that single source of truth.

Base tooling:

• Debian trixie (latest stable)
• Node.js (LTS), uv (Python tooling), rustup (Rust on-demand)
• AWS CLI v2 + AWS Bedrock-ready config
• MemPalace + MCP server — persistent agent memory across sessions, queryable via mempalace_* tools inside pi
• Gitea MCP server
• Dev tools: neovim (LazyVim defaults), tmux, bat, eza, fzf, zoxide, ripgrep, git-lfs, make
• Shell: bash with history tuning, prefix-search bindings, fzf/zoxide integration
• Host-OS-agnostic LAN access — on VM-backed hosts (macOS OrbStack / Docker Desktop) the host is set up as an SSH jump to reach LAN peers (dssh alias; DEVBOX_LAN_ACCESS/HOST_SSH_USER). No-op on native Linux.

pi and companions:

• pi (@earendil-works/pi-coding-agent) — baked at /usr/bin/pi, version set by the pi-only base build
• 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 can read/write the same palace as opencode-devbox

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

Versioning

Tags follow the pi npm version: v0.74.0, v0.75.0, etc. latest always points at the most recent release. The pi binary is inherited from joakimp/pi-devbox:base-pi-only, so each release follows an opencode-devbox release that bakes the target pi version. (base-pi-only is an internal building-block tag — pull latest or a vX.Y.Z tag instead.)

For container-level rebuilds on the same pi version (security updates, base bumps, fixes) the tag gets a letter suffix: v0.74.0b, v0.74.0c, …

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

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
• Base image: https://gitea.jordbo.se/joakimp/opencode-devbox (Hub: joakimp/opencode-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

License

MIT (the image; pi and the bundled tools each carry their own licenses).