pi
efd254f4e6
The Hub description still described the pre-v1.0.0 reality (tags follow
pi npm version, builds FROM joakimp/pi-devbox:base-pi-only, opencode-
devbox lineage as source of truth) — none of that has been true since
v1.0.0 decoupled. End users on Hub got a misleading story.
DOCKER_HUB.md changes:
- Versioning section rewritten: semver from v1.0.0, with a deprecation
note for the pre-v1.0.0 v{pi_version}[letter] scheme.
- New 'Build pipeline' section briefly explains the two-phase
base/variant content-addressed structure so users understand what
base-<hash> and base-latest tags are for.
- New 'Document and image tooling' section (pandoc, graphviz,
imagemagick) added since these are new in v1.0.0 and broadly useful.
- Tealdeer noted (vs the old Node tldr).
- Tmux 0-indexing called out (relevant for future :latest-studio
variant).
- Removed all 'pi-only build' / 'FROM base-pi-only' / 'opencode-devbox
bakes the pi version' framing — pi-devbox is now self-contained.
- New {{PI_VERSION}} placeholder in 4 locations so the Hub description
always shows which pi is in :latest.
Workflow change:
- update-description step now substitutes {{PI_VERSION}} placeholders
in DOCKER_HUB.md before sending to Hub. PI_VERSION comes from the
resolve-versions output (same one baked into the image), so the page
and image can never disagree. Sanity-check fails the step if any
unsubstituted placeholder remains.
155 lines
8.5 KiB
Markdown
155 lines
8.5 KiB
Markdown
# pi-devbox
|
|
|
|
A self-contained Docker container for the [pi coding-agent](https://github.com/earendil-works/pi) — 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](#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: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. |
|
|
|
|
## Quick start
|
|
|
|
One-shot, no persistence:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — installed at `/usr/bin/pi`
|
|
- **[pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)** — keybindings (mosh/tmux-friendly Shift+Enter, Ctrl+J, Alt+J newline bindings), AWS env loader, settings template
|
|
- **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — 7 user-facing extensions: `ext-toggle`, `mcp-loader`, `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive`
|
|
- **`fork`** ([pi-fork](https://github.com/elpapi42/pi-fork)) and **`recall`** ([pi-observational-memory](https://github.com/elpapi42/pi-observational-memory)) tools
|
|
- **mempalace bridge** — MCP extension auto-symlinked so pi reads/writes the host-mounted palace
|
|
|
|
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:
|
|
```bash
|
|
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 **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/joakimp/mempalace
|
|
|
|
## License
|
|
|
|
MIT (the image; pi and the bundled tools each carry their own licenses).
|