joakimp/pi-devbox repository overview

⁠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.

⁠Image variants

⁠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 1.0.0 (@earendil-works/pi-coding-agent⁠) — installed at /usr/bin/pi, pinned to an audited version (not npm latest)
• pi-atelier — TUI sidebar (ordered panels, split-pane, themes), vendored at /opt/pi-atelier and pinned to an audited tag; the exact tag is in the image labels (se.jordbo.pi-devbox.pi-atelier-version) and /etc/pi-devbox/build-manifest.json
• 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.

Terminal UI mode — fullscreen by default. pi 1.0.0 made the TUI fullscreen, and this image adopts upstream's default. Fullscreen uses the terminal's alternate screen, so the transcript no longer lands in your terminal's (or tmux's) native scrollback. To get the previous behaviour back, set "tuiMode": "regular" in ~/.pi/agent/settings.json, or pass pi --tui-mode regular for a single session. The bundled pi-atelier sidebar works in both modes. See the README for the related fullscreenExitOutput / fullscreenScrollbar / fullscreenCopyOnSelect / fullscreenWheelScrollLines settings — the last one behaves differently over SSH, which is how this container is usually driven.

⁠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.
• Typst — markup-based typesetting, used as pandoc's --pdf-engine
• graphviz (dot) — diagram rendering pipelines
• imagemagick (magick) — image conversion / resizing

⁠Browser automation

• agent-browser — CLI for driving a real browser (open pages, click/fill/eval, snapshot the DOM, screenshots) so agents can verify front-end work instead of guessing
• Playwright + a headless Chromium are pre-installed and pinned together; AGENT_BROWSER_EXECUTABLE_PATH is preset to the baked browser, so agent-browser open <url> works out of the box with no setup
• socat — TCP bridge used to expose the pi-studio server outside the container's loopback

⁠Modern CLI tooling

• Editor: neovim (system-wide termguicolors default; bring your own config/plugins), tmux (configured for 0-indexed sessions)
• Search/nav: ripgrep, fd, fzf, zoxide
• Display: bat, eza, htop, tree
• Data: jq, yq, sqlite3, bc/dc, column
• 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
  

  Copy
• Node.js v24 LTS + 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 1.0.0 for :latest) and asserted by smoke tests to match what's documented — version drift is caught at CI time, not on user pull.

⁠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.

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

⁠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⁠.