joakimp/pi-devbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
43cd6e22f2abe44593af2f1f4405b3001601db94
pi-devbox/DOCKER_HUB.md
T
joakimp 43cd6e22f2
Publish Docker Image / resolve-versions (push) Successful in 9s
Details
Lint / actionlint (push) Successful in 15s
Details
Lint / hadolint (push) Successful in 13s
Details
Publish Docker Image / base-decide (push) Successful in 8s
Details
Publish Docker Image / build-base (push) Successful in 41m22s
Details
Publish Docker Image / smoke-studio (push) Successful in 5m16s
Details
Publish Docker Image / smoke (push) Successful in 7m31s
Details
Publish Docker Image / build-variant-studio (push) Successful in 18m31s
Details
Publish Docker Image / build-variant (push) Successful in 27m18s
Details
Publish Docker Image / promote-base-latest (push) Successful in 11s
Details
Publish Docker Image / update-description (push) Successful in 12s
Details
v1.7.0: bundle pi-atelier at a pinned tag; pin pi to an audited 0.84.1 
Two changes that belong together, because the first is what makes the second
dangerous to get wrong.

pi-atelier (TUI sidebar + status rail) is now vendored to /opt/pi-atelier at
PI_ATELIER_REF=v0.8.0 and registered by entrypoint-user.sh — the pi-fork /
pi-observational-memory / pi-studio pattern, deliberately NOT
`pi install npm:pi-atelier`, which writes into ~/.pi/npm-global on the config
volume where it shadows the image and pins nothing. Unlike its siblings it gets
no `npm install`: atelier declares zero runtime deps (peerDeps only, satisfied by
the baked pi) and has no build step, so pi loads its TypeScript straight from the
checkout via package.json `pi.extensions`.

pi is no longer resolved to npm `latest` at build time. The pin lives in
Dockerfile.variant and CI reads it from there, so a local `docker build` and a CI
release ship the same versions by construction. The pin is a CHECKPOINT, NOT A
FREEZE: bumping stays a one-line change; what stops is *unreviewed* adoption of
whatever shipped that morning, in the same build that then gets tagged and
published. CI fails when a pin is not concrete or not actually published on npm,
and warns — never adopts — when npm latest moves ahead, naming what to re-check.

Why this pairing needed care: pi-atelier 0.6.0/0.7.0 wrap pi's PRIVATE TUI
renderer, and under pi 0.84 that wrapper recurses — pi hangs at startup burning
CPU with no error. Upstream fixed the recursion in 0.7.1 and restored the
non-overlapping split in 0.7.2; 0.8.0 is additive on top. atelier's own
peerDependencies still say >=0.80.7, which does not express that floor, so
nothing in npm metadata could have warned us. The floor is therefore encoded as
an executable rule — pi >= 0.84 => pi-atelier >= 0.7.1 — asserted in both
smoke-test.sh (build time) and recreate-sanity-check.sh (after a real recreate),
verified against a 4x4 version matrix.

Existing volumes needed migration, not just vendoring: a hand-installed
`npm:pi-atelier` entry is counted as already-registered by the entrypoint guard,
so every existing volume would have kept its unpinned npm copy — and a 0.6.x copy
next to pi 0.84 is exactly the startup hang. The entrypoint now drops that one
exact string (settings.json.bak.atelier.<ts> backup, distinct prefix so it cannot
clobber the template merge's backup in the same second) and lets the pinned /opt
copy register. Tested against a real settings.json: only that entry removed,
other packages and all keys intact, idempotent, and unparseable JSON leaves the
file untouched. DEVBOX_ATELIER=0 opts out entirely — in the entrypoint rather
than via `pi uninstall`, because this component's failure mode is "pi will not
start", which cannot be repaired from inside pi.

0.84.1 was audited for this release, not merely adopted: theme/TUI changes are
additive, the session format is unchanged (CURRENT_SESSION_VERSION = 3 in both
0.83.0 and 0.84.1 with an identical migrateV1ToV2/migrateV2ToV3 ladder, so
existing transcripts are neither migrated nor at risk and pi-session-repair stays
valid), and the Node engine floor is unmoved at >=22.19.0. CI resolves the
atelier tag to its PEELED commit SHA — atelier uses annotated tags, so the
unpeeled ref is a tag object, not a commit; pi-studio's lightweight tags never
exposed that distinction.

Also: docs for overriding the read-only ~/.ssh/config from the container —
container-only keys in ~/.ssh-local, hardened authorized_keys, the fact that
`from=` must allow the HOST's addresses because container egress is NAT'd through
it, and the macOS-only-keyword trap (`UseKeychain` is fatal to Linux OpenSSH and
takes out dssh/pi --ssh while the host keeps working). Corrects two claims in
"Naming LAN peers": ssh-lan.conf is not ProxyJump-only, and first-time creation
does need one restart because the Include is emitted only when the file already
exists at start.
2026-08-07 21:34:41 +02:00

10 KiB
Raw Blame History

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

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

License

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

Reference in New Issue View Git Blame Copy Permalink