pi-devbox/AGENTS.md

AGENTS.md — pi-devbox

Container image that adds pi coding-agent on top of the opencode-devbox base image.

Repository layout

• Dockerfile — single-stage build, FROM opencode-devbox:base-latest, installs pi + companion repos
• docker-compose.yml — compose file for local use
• .env.example — environment variable template
• scripts/smoke-test.sh — sanity checks run by CI before pushing to Docker Hub
• .gitea/workflows/docker-publish.yml — CI pipeline: smoke amd64 → multi-arch push → update Hub description

Versioning scheme

• Tags follow the pi npm version: v{pi_version}[letter]
• Bump PI_VERSION build-arg default in Dockerfile when cutting a new release
• Docker Hub: joakimp/pi-devbox:vX.Y.Z + joakimp/pi-devbox:latest

Release-day checklist

1. Bump PI_VERSION in Dockerfile (or leave as latest to pick up current)
2. Update CHANGELOG.md: promote Unreleased → vX.Y.Z — YYYY-MM-DD
3. Add fresh ## Unreleased section
4. Commit, tag vX.Y.Z, push tag → CI fires automatically

Key facts

• Base image: joakimp/opencode-devbox:base-latest — rebuilt whenever opencode-devbox cuts a new base
• pi binary: baked at /usr/bin/pi (system npm prefix); NPM_CONFIG_PREFIX=/home/developer/.pi/npm-global at runtime so user-installed pi/packages land on the named volume
• Companion repos: pi-toolkit and pi-extensions cloned to /opt/ at build time; entrypoint-user.sh (inherited from base) deploys symlinks to ~/.pi/agent/ on container start
• MemPalace: fully operational — inherited from base image; bridge extension deployed by entrypoint

Conventions

• Do NOT call mempalace-toolkit/install.sh in the Dockerfile — the base entrypoint handles it
• NPM_CONFIG_PREFIX=/usr must be set per-RUN for any build-time npm install -g to keep baked binaries off the volume-shadowed path
• The smoke test threshold is 2200 MB — update if the image legitimately grows past it