setup-hooks.sh used to WRITE .git/hooks/pre-commit from a heredoc. That makes the
running hook a copy of the versioned intent, and a copy drifts. It already had:
the hook installed on this machine was an older revision than this script emits,
having lost the Linux gitleaks install hint (`uname -s` line) that the heredoc has.
Nothing reported that, because a stale hook still prints a reassuring banner.
The hook body is now a tracked file at hooks/pre-commit -- extracted byte-for-byte
from the heredoc, so this commit changes where the hook lives, not what it does --
wired via `git config core.hooksPath hooks`. git then executes the tracked file
itself, so the hook that runs and the hook in history cannot disagree. This is the
convention docker-compose-repo already uses.
setup-hooks.sh keeps its name (README references it) and now activates rather than
generates. It also warns if .git/hooks/pre-commit still exists, because after
core.hooksPath is set that file is INERT and silently shadowed -- a decoy that looks
like protection. The leftover copy on this clone was removed.
VERIFIED, and the first attempt was a false pass worth recording: a planted
`AKIAIOSFODNN7EXAMPLE` was NOT blocked and the test commit went through. The gate
was fine -- gitleaks ALLOWLISTS that string, since it is AWS's own documentation
example. A control built from a well-known example credential proves nothing. That
commit was reset (HEAD back to 69fc80a = origin/main) and the control rebuilt from a
synthetic RSA private key block, first confirmed detectable by two independent routes
(`gitleaks detect --no-git` on the file, then `gitleaks protect --staged` in-repo)
BEFORE being trusted as a control. Through the hook: rc=1, "commit blocked", HEAD
unchanged. Also confirmed core.hooksPath=hooks is set and shellcheck is clean on
both files. Test artefacts deleted; nothing leaked into history.
Not tagged yet; this is the v2.9.0 changeset landing on main.
Added
- agent-browser + a Playwright-managed headless Chromium in the base (~625 MB
after deleting the redundant chromium_headless_shell build), so an agent can
drive a real browser and VERIFY front-end work instead of assuming it renders.
Ported from pi-devbox. AGENT_BROWSER_EXECUTABLE_PATH points at the stable
symlink /usr/local/bin/agent-chrome, which the Dockerfile resolves with `find`
rather than hardcoding: Playwright's browser dir is per-version AND per-arch
(chrome-linux on arm64, chrome-linux64 on amd64), and the headless shell binary
is named chrome-headless-shell so `-name chrome` skips it.
- opencode-devbox-version: a reader for the build manifest. The image has baked
ground truth to /etc/opencode-devbox/build-manifest.json for several releases,
but nothing read it and nothing printed it — so "which image am I running?"
meant knowing the path by heart. Three modes (--json/--quiet/human), plus a
live-vs-baked drift check, because NPM_CONFIG_PREFIX points at the persistent
config volume and a user `npm install -g opencode` can shadow the baked binary.
entrypoint-user.sh prints it as its first output.
- ENV COLORTERM=truecolor, completing a true-colour story the image already
half-shipped (terminfo entries + Neovim termguicolors, but no capability
advertisement, so bat/delta fell back to 256 colours).
- Smoke assertions for agent-browser, that agent-chrome resolves to an
executable (catches a Playwright layout change, not just a dangling symlink),
COLORTERM, the manifest's release_tag, and all three version-command modes.
Changed
- opencode 1.17.20 -> 1.18.13. Verified by diffing upstream source, not release
notes: core config.ts, config/provider.ts and schema.json are byte-identical,
so generate-config.py needs no change. 1.18.13 (published mid-audit) was
re-verified separately — 249 files in the compare payload, under GitHub's
300-file cap, so the list is complete rather than truncated; content is the
Electron app plus localisation; the five contract-surface files hash identical
at both tags. The bg-subagents removal trigger has NOT fired: runtime-flags.ts
still gates the flag behind OPENCODE_EXPERIMENTAL at all three tags.
- yq: dropped Debian's apt package (the unrelated Python kislyuk/yq — jq syntax,
3.x line) for mikefarah's Go yq v4 from GitHub. The cloud-init repo's
provision.sh/deploy.sh need v4 syntax, and THIRD_PARTY.md already credited
"yq (mikefarah)" while the image shipped the Python one, so this also closes a
documented-vs-shipped mismatch. Smoke pins the contract to mikefarah v4.
BEHAVIOUR CHANGE for any in-image script calling yq with jq-style syntax.
- mempalace pin 3.5.0 -> 3.6.0, in lockstep with pi-devbox (5724302). Reviewed
for MCP tool-schema changes before bumping — none, and nothing touches
diary_write.
- Default models -> claude-opus-5 (anthropic, and bedrock's
global.anthropic.claude-opus-5) and openai/gpt-5.6. gpt-5.4 had gone stale:
gpt-5.6 shipped four days before the v2.8.0 cut. Affects only new containers
with no OPENCODE_MODEL and no existing config.
- Smoke size thresholds +650 MB (base 2950->3600, omos 3650->4300), sized to
keep the same ~250 MB headroom so the guardrail still catches runaway growth
rather than routine apt drift. Do NOT copy pi-devbox's number: it sums
`docker history`, this repo uses `docker image inspect .Size`.
Documentation
- New README section "Choosing a provider and model", making explicit that the
baked defaults are only defaults and nobody is locked to Anthropic/Bedrock,
including the three real gotchas: defaults seed only a NEW config, an existing
opencode.jsonc on the persistent volume is never rewritten, and switching
model needs no rebuild.
- New README section "Browser automation (agent-browser)"; opencode-devbox-version
documented under Build provenance; COLORTERM under Terminal compatibility.
- README Build Args table drift fixed — FOUR missing args added
(AGENT_BROWSER_VERSION, PLAYWRIGHT_VERSION, YQ_VERSION and GITLEAKS_VERSION,
the last of which had existed as an ARG but was never listed), plus rows for
the two pinned args absent entirely (MEMPALACE_VERSION, DEBIAN_VERSION), plus
a refreshed stale OPENCODE_VERSION example. Third consecutive release to find
drift in this table.
- AGENTS.md: the stale MemPalace anyOf convention rewritten. It described a perl
RUN block already DELETED at the 3.5.0 bump and asserted "PyPI latest is 3.4.0
(== our pin), no release contains the fix yet, the workaround must stay" — all
three false. Replaced with a pin-review rule. Two new conventions added: the
agent-browser/Chromium size coupling, and the yq identity trap.
- THIRD_PARTY.md: agent-browser, Playwright, Chromium.
Verified locally with the CI-pinned hadolint 2.14.0 and actionlint 1.7.7, the
shell guard, DOCKER_HUB.md sync, bash -n, py_compile, and by generating the
config for all three providers.
- Dockerfile.base + AGENTS.md: bg-subagents removal-trigger last-checked markers
1.17.15/omos 2.1.0 -> 1.17.20/omos 2.2.0 (re-verified; trigger still not fired).
The Dockerfile.base comment edit changes the base-content hash, so base-<hash>
advances and the base image rebuilds on the next release.
- README: refresh stale OPENCODE_VERSION build-arg examples (1.5.0, 1.17.8 -> 1.17.20);
link THIRD_PARTY.md from the License section.
- AGENTS.md: adding a new floated *_VERSION ARG must also update the README Build Args
table (closes the coupling gap that hid MICRO/TEALDEER/TYPST for 3 releases).
- CHANGELOG Unreleased: record both under Changed + Documentation.
Features that shipped without README prose are now documented:
- PDF export (pandoc --pdf-engine=typst) — new Document conversion section
- Terminal TERM/terminfo support (ncurses-term, kitty-terminfo, xterm-ghostty)
- Neovim 24-bit colour default (termguicolors via system sysinit.vim)
- first-shell host SSH reachability check (Shell defaults list)
- baked global gitignore (patterns + core.excludesFile wiring)
- Build Args table: add MICRO_VERSION, TEALDEER_VERSION, TYPST_VERSION
Docs-only; noted under CHANGELOG Unreleased. Hub template and .env.example
were already accurate. Drift found via a v2.4.0+ CHANGELOG-vs-docs audit.
opencode gates native background subagents behind this experimental flag;
oh-my-opencode-slim V2+ makes background orchestration its default workflow,
so the omos variant was effectively degraded without it. Set as a base-level
ENV (both variants, harmless for plain opencode) and overridable at runtime.
Documented in lockstep: README env table, .env.example, CHANGELOG Unreleased,
and AGENTS.md (with a removal trigger for when opencode promotes it out of
experimental). smoke-test asserts the var is baked into the image env.
Also folds the prior CLI-tools additions into the CHANGELOG Unreleased block.
Added:
- generate-config.py registers mempalace as a remote MCP endpoint when
MEMPALACE_REMOTE_URL is set (MEMPALACE_REMOTE_TOKEN -> Bearer), else the local
stdio command as before. Same env contract as pi-devbox's bridge.
- docker-compose.mempalace.yml: optional shared server (mempalace-mcp --transport http),
loopback-bound by default.
- compose (both) + .env.example(.shared): MEMPALACE_REMOTE_URL/TOKEN + local-vs-external docs.
Fixed:
- validate.yml: skip validate-base/validate-omos on base-changing commits
(base-change-warning now exports base_changed). Previously a commit that changed
the base AND tightened smoke-test.sh in lockstep (v2.4.0 nano/micro) hard-failed
against the stale base-latest until the release rebuilt it. actionlint clean.
README + CHANGELOG (Unreleased).
The image shipped only nvim (EDITOR=nvim), a modal vi-style editor. Add
both a classic and a modern non-modal option so users who aren't
comfortable with vi keybindings have a choice:
- nano (apt): ~2.8 MB installed; deps (libc6, libncursesw6, libtinfo6)
already present via nvim/less/htop/tmux, so no extra packages pulled in.
- micro: ~12 MB single static Go binary from GitHub releases (same pattern
as bat/eza/zoxide). Desktop-style keys (Ctrl+S/Ctrl+Q), mouse, syntax
highlighting. ARG MICRO_VERSION pins; defaults to latest.
Combined ~15 MB (well within the smoke size threshold's ~250 MB headroom,
so no threshold bump). EDITOR stays nvim; both editors are opt-in
(export EDITOR=micro | nano). Uses the canonical micro-editor/micro URL
because the old zyedidia/micro org rename makes /releases/latest redirect
to another /latest, defeating the tag-parsing latest-resolution idiom
(independently verified: old org 302s to micro-editor/micro; both arch
tarballs HTTP 200; latest resolves to v2.0.15).
Base-image change, so it lands on the next base-<hash> rebuild. Updates
README (what's-inside tree + EDITOR note), CHANGELOG (Unreleased/Added),
and smoke-test.sh (nano + micro presence checks). Ported from pi-devbox
3a59e15.
DRIFT-STALE fixes (stale/misleading text corrected):
- README.md:160 — "on native Linux it does nothing" → accurate always-render
description (sidecar written on every OS; jump block still omitted on Linux)
- AGENTS.md:22 — setup-lan-access.sh "no-op on native Linux" → corrected to
always-render + removed now-redundant inline ControlPath/UserKnownHostsFile
sentence (that's what the sidecar does, not what the script detects)
- CHANGELOG.md:594 (v2.1.1 intro) — "no-op" → "(see v2.2.0)" historical note
- docs/plan-lan-access-and-pi-extensions.md:222 — annotated the completed
checkbox with the v2.2.0 refinement
GAP additions:
- README.md:212 — custom config section now describes opencode.jsonc.proposed
sidecar: written-on-diff, removed-on-match, never overwrites, one-line hint
- README.md build-args table — INSTALL_MEMPALACE_TOOLKIT row now mentions
MEMPALACE_TOOLKIT_REPO alongside MEMPALACE_TOOLKIT_REF
- README.md (after build-args table) — two new sections:
"Building a fork / relocated build" — MEMPALACE_TOOLKIT_REPO build-arg
table + two-step docker build example + credentials note
"Build provenance (labels + manifest)" — docker inspect + run examples,
OCI label set, ground-truth manifest path
Version string drift: no hard-coded 1.17.7 found outside CHANGELOG (all
occurrences are historical release entries — correct by definition).
CI-internal items (resolve-versions, check-base-hash.sh): no existing doc
described these mechanics, so no update needed.
The image's default CMD is bash -l, so 'docker compose run --rm devbox'
with no command drops into a login shell; you pass 'opencode' explicitly to
start the harness. The README quick-start claimed the opposite and carried a
garbled 'Use bash instead of (no command)' half-sentence; the same error was
mirrored in the Hub HUB_TEMPLATE. Fix both and regenerate DOCKER_HUB.md.
Doc-only — no image bytes change.
Deploy the five oh-my-opencode-slim bundled skills (clonedeps, codemap,
deepwork, oh-my-opencode-slim, simplify) by symlinking them from the image
path into ~/.agents/skills/ on every container start, instead of the
installer copying them into the persistent config volume on first run only.
Image-sourced links mean 'docker compose pull' + recreate refreshes the
skills with no installer run and no config reset; the old copy-on-first-run
froze them in the volume forever.
- entrypoint-user.sh: new non-fatal OMOS bundled-skills reconcile block
(runs after skillset deploy so OMOS wins the simplify collision; absolute
symlinks; gated by OMOS_SKILLS, now independent of ENABLE_OMOS). Both
installer calls now pass --skills=no. One-time migration backs up (never
deletes) frozen real copies in ~/.config/opencode/skills/ to .bak.<epoch>.
- scripts/smoke-test.sh: assert the bundled-skills source path on omos.
- Bump OPENCODE_VERSION 1.17.4 -> 1.17.5.
- Versioning: document the move to independent image semver (v2.0.0 was the
decouple point), mirroring pi-devbox. README/AGENTS/.env.example/CHANGELOG
updated; new docs/omos-skills.md.
PR-5 (per docs/CLEANUP-v2.0.0.md). Major release with two breaking changes:
1. pi fully removed (deprecated in v1.17.2). Gone: INSTALL_PI + all PI_*
build args; with-pi/omos-with-pi/pi-only variants; base-pi-only publish
job; all ~/.pi entrypoint wiring; the 3 pi smoke/validate/build-variant
CI jobs. Only base + omos variants remain (4 tags/release).
2. NPM_CONFIG_PREFIX relocated ~/.pi/npm-global -> ~/.config/opencode/npm-global
(persistent in both compose files). entrypoint-user.sh gains a one-time
migration shim that copies old global npm packages forward.
Also: opencode 1.17.2->1.17.4; DOCKER_HUB.md gains {{OPENCODE_VERSION}}
placeholder filled by CI at publish time (mirrors pi-devbox); full docs
drift sweep across README/AGENTS/.gitea-README/.env.example/manual-host-publish;
DOCKER_HUB.md regenerated + --check passes; both workflows YAML-valid;
all shell scripts pass bash -n.
opencode-ai 1.16.2 -> 1.17.2 (OPENCODE_VERSION).
Deprecate all pi support ahead of v2.0.0 removal (pi now ships from the
standalone joakimp/pi-devbox image, v1.0.0+, which no longer FROMs
base-pi-only):
- build-time stderr deprecation warning when INSTALL_PI=true
- README / DOCKER_HUB.md / AGENTS.md mark the with-pi/omos-with-pi/pi-only
variants + base-pi-only tag deprecated, point to pi-devbox
- docs/CLEANUP-v2.0.0.md committed as the removal plan
- CHANGELOG pre-announces the v2.0.0 NPM_CONFIG_PREFIX relocation
Harden mempalace install (mirrors pi-devbox):
- pin via MEMPALACE_VERSION ARG (default 3.4.0); unpinned install is what
swept in the broken schema
- idempotent, self-deactivating patch stripping the top-level anyOf from
mempalace_diary_write input_schema (Anthropic tools API rejects it).
Upstream: MemPalace/mempalace#1728, PR #1735
Fold prior Unreleased smoke-test pi-extensions readiness fix into v1.17.2.
The bind-mounted ~/.ssh/config is read before the baked Host * default and
SSH uses the first ControlPath it sees. A per-host block pointing ControlPath
under ~/.ssh/ (CGNAT-multiplexing pattern) wins but fails in-container because
~/.ssh is read-only, silently breaking pi --ssh <host> (falls back to local
tools). Documented the host-side fix: drop the override or repoint at the
writable /tmp/sshcm/. README + CHANGELOG only, no image change.
Persist ~/.ssh-local (devbox-ssh-local named volume) so the generated
LAN-jump key survives 'docker compose up --force-recreate'. Authorize
it on the host once per machine instead of after every container update.
setup-lan-access.sh now prints a copy-paste
'echo <pubkey> >> ~/.ssh/authorized_keys' line whenever it generates a
new key (not only when HOST_SSH_USER is unset), and stays silent once
the key is persisted. README + CHANGELOG updated.
- Fix: Include ~/.ssh/config was scoped to the Host host/mac block, so
dssh <peer> by name fell back to SSH defaults. Emit Host * scope reset
before every Include.
- Fix: redirect ControlPath to writable ~/.ssh-local sidecar (Mac config's
~/.ssh/cm path is read-only in the container, broke multiplexed hosts).
- Add: Include host-owned ~/.config/devbox-shell/ssh-lan.conf for named-peer
ProxyJump overrides (keeps image generic; peer names stay host-side).
- Add: opt-in DEVBOX_LAN_AUTOJUMP_PRIVATE=1 RFC1918 catch-all for roaming.
- Docs: README/.env.example/AGENTS/CHANGELOG + new ssh-lan.conf.example.
The pi-only variant was published as opencode-devbox:latest-pi-only —
an 'opencode-devbox' tag containing no opencode, which confused users.
- build-variant-pi-only now pushes joakimp/pi-devbox:base-pi-only[-vX.Y.Z]
instead of opencode-devbox:*-pi-only. New PI_IMAGE workflow env.
- Still built from the same Dockerfile.variant (single source of truth),
still smoke-tested by smoke-pi-only / validate-pi-only before publish.
- De-advertised pi-only from README, DOCKER_HUB (HUB_TEMPLATE), AGENTS,
.gitea/README. opencode-devbox now publishes 8 tags + base-latest.
- Documented in CHANGELOG (Unreleased) and the plan doc.
Note: old opencode-devbox:{latest,vX.Y.Z}-pi-only tags from v1.15.13b are
superseded and should be deleted from Docker Hub.
All opencode-devbox variants set INSTALL_OPENCODE=true, so pointing pi-devbox
at with-pi dragged opencode along and made it ~a re-tag of latest-with-pi.
Add a 5th variant pi-only (INSTALL_OPENCODE=false, INSTALL_PI=true): pi +
companions (toolkit, extensions, fork, recall) + base tooling, no opencode
(~145 MB lighter than with-pi).
- Dockerfile.variant: document pi-only in the variant table.
- CI docker-publish-split.yml: new smoke-pi-only + build-variant-pi-only jobs
(tags :VERSION-pi-only / :latest-pi-only, multi-arch); wired into
promote-base-latest and update-description needs.
- validate.yml: new validate-pi-only main-branch gate job.
- smoke-test.sh: accept --variant pi-only; threshold 2750 MB; opencode-absent
path already handled.
- Docs: HUB_TEMPLATE (regenerated DOCKER_HUB.md), README, AGENTS (variant/tag
counts 4->5, 8->10 tags), .gitea/README, manual-host-publish.sh (5 variants),
plan doc implementation note.
This is the single source of truth for joakimp/pi-devbox, which now FROMs
latest-pi-only. Versions unchanged (opencode 1.15.13, pi 0.78.0).
Item A — LAN access (base image):
- New rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh, invoked
non-fatally from entrypoint-user.sh. On VM-backed hosts (macOS OrbStack /
Docker Desktop, detected via host.docker.internal) it generates a writable
~/.ssh-local/config that uses the host as an SSH jump to reach LAN peers;
no-op on native Linux. Ships the mechanism (generic 'host' jump alias),
not policy (targets stay in the user's bind-mounted ~/.ssh/config).
- New env knobs: DEVBOX_LAN_ACCESS (auto|jump|off), HOST_SSH_USER,
DEVBOX_HOST_ALIAS. dssh/dscp aliases in .bash_aliases (guarded).
Item B — pi-fork (fork) + pi-observational-memory (recall) in pi variants:
- Dockerfile.variant clones both elpapi42 repos to /opt and runs npm install
there at build time (local-path 'pi install' does not npm-install, so deps
must be present to load). New args PI_FORK_REPO/REF, PI_OBSMEM_REPO/REF.
- entrypoint-user.sh registers them at runtime via 'pi install /opt/<pkg>'
(instant, in-place, idempotent; tools bind on next pi start).
- CI resolve-versions resolves each repo's master HEAD to a commit SHA and
passes PI_FORK_REF/PI_OBSMEM_REF — same cache-hit guard as PI_VERSION.
- smoke-test asserts /opt clones + node_modules + settings.json registration;
size thresholds bumped (with-pi 2700->2900, omos-with-pi 3700->3900).
Versions unchanged (opencode 1.15.13, pi 0.78.0 — both still latest).
Docs: README LAN section + env table, .env.example, AGENTS.md, CHANGELOG.
Plan recorded in docs/plan-lan-access-and-pi-extensions.md.
Both tools are used as part of the secret-management setup in several
of the repos this devbox operates on (gitleaks pre-commit hook +
git-crypt for selectively-encrypted canonical config). Having them in
the container means hooks fire correctly inside instead of warning
'gitleaks not installed' on every commit.
git-crypt was already installed via apt in Dockerfile.base (line 58),
just unasserted by smoke and unmentioned in user-facing docs.
gitleaks is new: Go-compiled binary fetched from GitHub releases via
the same /releases/latest redirect-resolution pattern as gosu, fzf,
git-lfs, etc. Arch suffix is 'x64' (not 'x86_64' / 'amd64') on this
project — flagged in the Dockerfile comment and in AGENTS.md's
floated-binaries gotcha list.
Adds ~21 MB to the base layer (gitleaks 8.30.1 binary). No variant
threshold bumps needed (2500–3700 MB envelope, 21 MB is noise).
CHANGES
Dockerfile.base — new GITLEAKS_VERSION=latest ARG + install RUN
right after the git-lfs block. Multi-arch (linux/amd64=x64,
linux/arm64=arm64). Echoes resolved version + runs 'gitleaks version'
to fail the build on any install error.
scripts/smoke-test.sh — git-crypt and gitleaks added to the
'Resolved component versions' table (printed first thing in CI logs)
and to the 'Core binaries' assertion list (run helper). Smoke now
fails fast if either binary regresses.
README.md — 'What's in the image' tree line names gitleaks alongside
the existing git-crypt.
AGENTS.md — gitleaks added to the 'GitHub-sourced binaries float by
default' list with a new clause flagging project-specific arch-name
deviations (gitleaks=x64, bat/eza/zoxide=x86_64/aarch64, gosu=
amd64/arm64). Saves the next person from the 'why does this not
download' debugging session.
CHANGELOG.md — sub-entry under existing Unreleased, before the
PI_VERSION/OMOS_VERSION cache-hit fix entry.
DOWNSTREAM IMPACT
This is a base-layer change — base-decide will compute a fresh
base-<hash>, build-base will run (no cache hit), all four variants
will rebuild. First real base rebuild since v1.14.50b. Pi-devbox's
next FROM base-latest pull picks up gitleaks automatically with no
Dockerfile change there.
Verified end-to-end on host: gitleaks 8.30.1 21 MB binary extracts
cleanly from the URL the Dockerfile constructs and 'gitleaks version'
prints '8.30.1'.
Holding off on tagging — opencode + pi upstreams unchanged at 1.15.10
and 0.75.5 respectively. Will ride along with the next upstream-bump
release rather than burning a base rebuild on a no-upstream-change
container-only roll.
The previous Quick Start in both surfaces led with 'git clone',
which is overkill for users who just want to run the published image.
Match pi-devbox's pattern: lead with 'mkdir; curl docker-compose.yml;
curl .env.example; edit .env; docker compose run --rm devbox'. Keep
the git-clone path as 'for hackers/forkers'.
Required pre-step: make the gitea repo public so unauthenticated
curl to the raw URL works (done out of band — repo was private until
this commit landed).
Pi moved to its new home at earendil-works on 2026-05-07
(https://pi.dev/news/2026/5/7/pi-has-a-new-home).
The old @mariozechner/pi-coding-agent npm package is deprecated with
the explicit message 'please use @earendil-works/pi-coding-agent
instead going forward', and the version stream has moved on (old
top-out 0.73.1; new currently 0.74.0). Anyone npm-installing the old
name today gets a deprecation warning + a stale binary, so this is
a non-optional migration before the next tagged release.
Sweep:
- Dockerfile (production single-Dockerfile path) and Dockerfile.variant
(split-base path on main): npm install -g target updated.
- README, AGENTS, HUB_TEMPLATE: github.com/mariozechner/pi-coding-agent
URL refs (which now 404) -> github.com/earendil-works/pi.
- DOCKER_HUB.md regenerated (5529 bytes, ~78% headroom).
- CHANGELOG Unreleased: rename entry added with migration context.
Brew install references (`brew install pi-coding-agent`) left as-is:
formula still works at 0.73.1 and a homebrew tap update is tracked
upstream at earendil-works/pi#2755.
Historical CHANGELOG entries: only github URL refs updated (the
package name was never spelled out in those entries; we're correcting
dead hyperlinks, not rewriting feature descriptions).
Was stale:
- Claimed 6 pi-extensions (actually 7 — mcp-loader was added in
pi-extensions 141bf64 / 7eec49b / 37cc49e but the count was never
propagated here).
- No mention of mcp-loader's dual-transport (local stdio + remote
streamable-HTTP per MCP spec 2025-03-26) or the /mcp slash command.
- Mempalace bridge bullet didn't note that it coexists with mcp-loader
rather than being replaced by it (don't list mempalace in mcp block).
- No explicit 'no MCP servers baked in' line, leaving readers to
guess whether searxng/context7 ship by default.
Each extension now gets a one-line description; mcp-loader gets a
paragraph covering its capabilities and a link to the pi-extensions
AGENTS for transport detail. Added an opt-in note for MCP servers.
NPM_CONFIG_PREFIX is now /home/developer/.pi/npm-global, with that
prefix's bin/ prepended to PATH. Without this, 'pi install npm:<pkg>'
(and any 'npm install -g') by the developer user would EACCES against
the system prefix (/usr).
The new prefix lives on the devbox-pi-config named volume, so:
- User-installed pi packages (themes, skills, extensions) survive
container recreate AND image rebuild, complementing pi's auto-
restore from settings.json with one less cold-start step.
- A user-driven 'npm install -g @mariozechner/pi-coding-agent' lands
on the volume and wins over the baked pi via PATH order.
Build-time 'npm install -g' calls (opencode, pi, oh-my-opencode-slim)
are unaffected: the new ENVs are declared after those steps in the
Dockerfile, so the baked binaries still install to /usr at build time
and are not shadowed by the volume mount at runtime.
Verified end-to-end with a Bun-driven smoke test: as developer,
'npm install -g cowsay' inside the container succeeds, the binary
lands on PATH, and survives a fresh container against the same volume.
DOCKER_HUB.md regenerated (24997/25000 bytes, 3-byte headroom — was
138 before; future README additions to the persistence section need
to trim something else first).
Docs updated: Dockerfile inline comments, README persistence section,
AGENTS install contract, DOCKER_HUB persistence table, .env.example
notes, CHANGELOG Unreleased entry.
The v1.14.41b release expanded the CI matrix to four image variants
and pushed eight tags total, but the docs lagged behind:
- DOCKER_HUB.md's Image Variants table still listed only base + omos.
- README.md's pi section only described building from source; no
mention that prebuilt latest-with-pi / latest-omos-with-pi tags
exist (asymmetric vs the OMOS section which does mention latest-omos).
Fix:
- generate-dockerhub-md.py HEADER: extend Image Variants table to all
four variants (base, omos, with-pi, omos-with-pi).
- README.md pi section: add a Setup subsection mentioning the prebuilt
pi-enabled tags, mirroring the OMOS section's pattern.
- Regenerate DOCKER_HUB.md (22975 bytes, well under the 25k Hub limit).
The pi section itself remains intentionally dropped from DOCKER_HUB.md
to fit the 25k limit (SECTION_RULES); the Image Variants table at the
top is sufficient signal for Hub readers.
Optional integration of pi-coding-agent alongside opencode in the same
container. Both harnesses share the mempalace install and palace path —
wing/diary entries are mutually visible.
Build:
--build-arg INSTALL_PI=true # opt-in
--build-arg PI_VERSION=0.73.1 # pin a version (default: latest)
--build-arg INSTALL_OPENCODE=false # build pi-only image
Dockerfile:
• New INSTALL_PI block: npm install -g @mariozechner/pi-coding-agent
+ git-clones pi-toolkit and pi-extensions to /opt/.
• Existing opencode install gated behind new INSTALL_OPENCODE arg
(default true; existing builds unaffected).
• mkdir adds ~/.pi/agent/extensions for the named volume mount root.
• CMD changed from ['opencode'] to ['bash', '-l']. compose run --rm
devbox now drops to a login shell so users pick the harness; pass
'opencode' or 'pi' explicitly to launch directly. compose exec
workflows are unaffected (bypass entrypoint+CMD).
entrypoint.sh:
• Adds ~/.pi to volume ownership loop.
entrypoint-user.sh:
• New 'pi: deploy toolkit + extensions + mempalace bridge' block runs
pi-toolkit/install.sh, pi-extensions/install.sh, settings.json
template bootstrap, then symlinks the mempalace.ts bridge directly.
Order: toolkit before extensions before bridge. mempalace-toolkit's
full install.sh is intentionally NOT called (its install_skill
would race with skillset auto-deploy --prune-stale).
docker-compose.yml:
• New devbox-pi-config named volume mounted at /home/developer/.pi.
Persists user toggles (/ext-disabled extensions) and settings.json
edits across container recreate. Mirrors devbox-opencode-config
pattern from v1.14.33.
scripts/smoke-test.sh:
• New --variant with-pi (threshold 2700 MB) and --variant omos-with-pi
(3400 MB).
• Pi assertions gated on `command -v pi`: version, /opt/pi-toolkit
clone HEAD, /opt/pi-extensions clone HEAD, deployed keybindings
symlink, ≥4 extension symlinks, mempalace.ts bridge symlink,
settings.json bootstrap.
• Pi state assertions use docker exec from the host (not 'run'),
since the container has no docker CLI.
• opencode core test now gated on INSTALL_OPENCODE presence.
scripts/generate-dockerhub-md.py:
• SECTION_RULES adds 'pi (alternative/complementary harness)': drop.
Section stays in README; dropped from DOCKER_HUB.md to keep under
the 25 kB Docker Hub limit.
Docs:
• README adds full 'pi (alternative/complementary harness)' section.
• AGENTS.md codifies pi install contract, deploy ordering, named
volume rationale, and CMD change.
• CHANGELOG.md gets an Unreleased entry.
• .env.example documents new build args.
• docker-compose.yml example args block updated.
Verification (local builds on arm64):
• Default (INSTALL_PI=false): 1871 MB, all assertions pass — no
regression.
• INSTALL_PI=true: 2110 MB (within 2700 threshold), 37 assertions
pass including pi version, all 7 extensions deployed (6 from
pi-extensions + mempalace.ts bridge), settings.json bootstrap.
Not yet:
• CI workflow updates to add -with-pi tag variants. Deferred until
local path stabilizes through user testing.
• pi-devbox separate repo for fully stripped pi-only image. Phase 2.
The scheduler templates in mempalace-toolkit's contrib/ assume
mempalace-session is available inside the container, but the image
never actually installed it. Users following the *-devbox scheduler
docs would silently lose the wrappers on every container recreate,
because the only way to get them was a post-hoc install.sh inside
the container — which lives in the ephemeral layer. The host-side
systemd timer would then fire, docker exec in, and hit
"mempalace-session: command not found".
Caught during runtime validation on 2026-04-30: host-side systemd
unit ran cleanly at 16:15 today, then the container was rebuilt
and recreated, and the wrappers were gone. The rebuild produced
an image that the scheduler template's own documented precondition
did not hold for.
Fix: new Dockerfile block clones mempalace-toolkit at build time
(depth-1) to /opt/mempalace-toolkit/, symlinks bin/mempalace-session
and bin/mempalace-docs into /usr/local/bin/, asserts both respond
to --help before the layer succeeds. Gated by
INSTALL_MEMPALACE_TOOLKIT=true (defaults on, depends on
INSTALL_MEMPALACE=true). Floated ref via MEMPALACE_TOOLKIT_REF=main
for auto-picking-up toolkit updates; override for reproducible
builds once the toolkit starts tagging releases.
Smoke test gains three assertions (mempalace-session --help,
mempalace-docs --help, symlink target check). Resolved-versions
preamble logs the toolkit git short-SHA alongside the other
floated components, so CI logs always record what got baked in.
README gains a Scheduled mining (mempalace-toolkit) subsection
and a build-args row. DOCKER_HUB.md regenerated; sync-check passes.
The mempalace Python package ships a 'mempalace-mcp' console entry
point; 'uv tool install' places it on PATH as a shim whose shebang
points at the isolated venv's Python. Our hand-rolled wrapper at
/usr/local/bin/mempalace-mcp-server was duplicating what uv installs
for free — one less file to maintain.
Fixes the MCP error users saw after the v1.14.28b → v1.14.29 upgrade
path: custom opencode.json files typically had the pre-v1.14.29
command ['python3', '-m', 'mempalace.mcp_server'] which worked with
the old pip install but fails silently after the uv-tool migration
because system python3 cannot import from the venv. Opencode surfaced
this as 'MCP error -32000: connection closed'.
- generate-config.py now emits ['mempalace-mcp'] and keys its detect
on shutil.which('mempalace-mcp').
- Dockerfile drops 'COPY rootfs/usr/local/bin/' and the chmod of the
wrapper. Build shrinks from 30 to 29 stages.
- rootfs/usr/local/bin/ removed entirely.
- Smoke test asserts /usr/local/bin/mempalace-mcp is executable and
prints its symlink target.
- README's MemPalace section shows ['mempalace-mcp'] and explicitly
warns against the old pattern with the observed failure mode.
- CHANGELOG adds a v1.14.29c entry.
Main changes:
- Extract opencode.json generation from entrypoint-user.sh into a
standalone Python script (rootfs/usr/local/lib/opencode-devbox/
generate-config.py). Preserves the never-overwrite-existing-config
guarantee. Cuts entrypoint-user.sh from 176 to 97 lines.
- Install MemPalace via 'uv tool install' into an isolated venv at
/opt/uv-tools/mempalace/ with a /usr/local/bin/mempalace-mcp-server
wrapper, replacing the 'pip install --break-system-packages' escape
hatch. The wrapper is what generate-config.py references in the
auto-generated opencode.json. Also fix 'mempalace init' in
entrypoint-user.sh to use --yes so first-start initialization isn't
interactive (this used to hang or print prompts into the user's
terminal). Gated by INSTALL_MEMPALACE build arg (default true) so
users who don't need AI memory can shave ~300 MB.
- Sentinel-file pattern in entrypoint.sh volume-ownership loop: write
.devbox-owner after a successful chown -R, skip the recursive walk
on subsequent starts when the sentinel matches FINAL_UID:FINAL_GID.
Cuts multi-second startup costs to milliseconds on large volumes
(nvim plugins, palace data). UID changes still trigger a full chown.
- Float all GitHub/Gitea-hosted binary versions: gosu, fzf, git-lfs,
neovim, bat, eza, zoxide, uv, gitea-mcp now default to 'latest' and
resolve the newest upstream release at build time via the /releases/
latest redirect. Go (go.dev JSON feed) and oh-my-opencode-slim (npm
@latest) likewise. Intentional pins still in place: OPENCODE_VERSION,
NODE_VERSION=22, DEBIAN_VERSION=trixie-slim. Each *_VERSION ARG
accepts an explicit value to lock a specific version when needed.
- New scripts/smoke-test.sh verifies binary presence, opencode startup,
entrypoint user drop, generate-config idempotency, bun's presence-
per-variant, and image size against thresholds (2500 MB base, 3000
MB OMOS). Prints resolved component versions as its first step so
CI logs always record what got baked into a given image.
- New .gitea/workflows/validate.yml runs on push to main and PRs:
single-arch amd64 build, smoke test, DOCKER_HUB.md sync check. Tag-
triggered docker-publish.yml now smoke-tests each variant on amd64
before the full multi-arch push.
- scripts/generate-dockerhub-md.py auto-generates DOCKER_HUB.md from
README.md using explicit SECTION_RULES. --check mode fails CI when
the committed file is out of sync. Enforces the 25 kB Docker Hub
limit. Adding a new README section forces an explicit keep/drop/
replace decision.
- Remove dead INSTALL_PYTHON build arg (was a no-op since mempalace
added python3 unconditionally).
Python 3 has been unconditionally present since the Debian trixie
upgrade (e58962a, Apr 13) — python3 3.13 ships as a transitive
dependency of the trixie base image. python3-pip (e1029bb) and
python3-venv (3a7ec45) were later added to the base layer on Apr 23
so Mason could install Python-based LSPs (ruff, ansible-lint) into
venvs on nvim startup. MemPalace's pip install (b9c08c3) just
piggybacks on what was already there.
In other words, INSTALL_PYTHON=true has been a no-op reinstall of
already-installed packages for two weeks before MemPalace existed.
The flag is dead weight and the docs that advertise it as meaningful
are misleading. Remove it everywhere.
Users who want Python tooling should use the pre-installed uv/uvx.
Install gitea-mcp v1.1.0 (Go binary from gitea.com/gitea/gitea-mcp)
using the same multi-arch pattern as gosu/fzf/bat. Provides 50+ MCP
tools for Gitea API — repos, issues, PRs, releases, branches, wiki,
and Actions.
Disabled by default in auto-generated opencode.json (requires
GITEA_ACCESS_TOKEN and GITEA_HOST to be useful). Users enable it by
setting those env vars in .env and flipping enabled to true in their
opencode.json.
Env vars forwarded into the container via docker-compose.yml and
docker-compose.shared.yml environment blocks. Same {env:VAR} pattern
as the GitHub MCP server.
Docs updated: README.md (new Gitea MCP section with setup steps),
DOCKER_HUB.md (tools list), CHANGELOG.md (v1.14.28b entry).
The ONNX embedding model (~79 MB) downloads to ~/.cache/chroma/ on
first mempalace search. Without persistence it re-downloads on every
container recreation. Add a separate devbox-chroma-cache volume
rather than mixing it into the palace data volume — model cache is
disposable (delete and re-download), palace data is precious (back
up and migrate). Both volumes are commented out by default (opt-in).
Updated README.md storage section to explain the two-volume split
and the air-gapped pre-population path. Added chroma cache row to
DOCKER_HUB.md data storage table.
Install mempalace via pip in the Dockerfile. Provides 29 MCP tools
for semantic search over conversation history, knowledge graph
queries, agent diaries, and wing/room/drawer management. Everything
runs locally — no API keys, no data egress.
Integration:
- Dockerfile: pip install mempalace (with --break-system-packages
for Debian trixie PEP 668 compliance)
- entrypoint-user.sh: auto-initializes palace for /workspace on
first run (idempotent, skips if palace exists)
- entrypoint.sh: adds ~/.mempalace to the volume ownership-fix loop
- docker-compose.yml + shared: optional devbox-palace named volume
at ~/.mempalace (commented out by default — user opts in)
Users configure MCP integration by adding a mempalace server entry
to their opencode.json. No wrapper plugin needed — the upstream
Python MCP server is used directly.
Docs updated: README.md (new MemPalace section with setup, MCP
config, usage examples, storage details), DOCKER_HUB.md (data
storage table + tools list), CHANGELOG.md (unreleased entry).
Mason LSP installs and Lazy plugin cache live at ~/.local/share/nvim,
which was in the container's writable layer. Every --force-recreate
triggered a full re-download of all plugins and LSP servers on next
nvim launch — slow and wasteful.
Add devbox-nvim-data named volume in docker-compose.yml and
docker-compose.shared.yml, add to entrypoint ownership-fix loop,
update persistence tables in README.md and DOCKER_HUB.md.
Zoxide stores its database at ~/.local/share/zoxide/db.zo. Without a
named volume, the 'z <fragment>' jump targets are lost on every
'docker compose up --force-recreate'.
Add devbox-zoxide named volume in docker-compose.yml and
docker-compose.shared.yml, add ~/.local/share/zoxide to the
entrypoint ownership-fix loop per AGENTS.md convention, and update
the data-persistence tables in README.md and DOCKER_HUB.md.
The previous note scoped the single-file bind-mount staleness bug to
Docker Desktop only. It actually affects ALL platforms including native
Linux: Docker bind-mounts the inode, not the path. Editors that do
atomic save (vim, nvim, VS Code, sed -i) create a new inode via
rename(), leaving the container pinned to the old unlinked one. This
is a kernel limitation (moby/moby#15793, open since 2015, unfixable).
Rewrite both the README.md caveat and the docker-compose.yml inline
note to describe the real mechanism (inode replacement), name the
affected editors, note that append-only writes are safe, and link to
the upstream issue.
On Docker Desktop (macOS/Windows), single-file bind-mounts can
silently stop propagating host edits — the file gets materialized
onto the VM's ext4 disk and reused forever. This affects anyone who
uncomments the ~/.bash_aliases or ~/.inputrc mount lines.
Add a caveat note in README.md's 'Overriding the defaults / Option A'
section with the verification command and the directory-mount
workaround. Add a matching inline NOTE comment in docker-compose.yml
above the commented mount lines. Linux hosts are unaffected.
The shared-machine section in README.md still claimed named volumes
were isolated by directory-name prefixing alone, which was the bug
we just fixed. Rewrite to document both modes (own-account with
automatic $USER fallback, shared-account with explicit SIGNUM) and
explicitly note that the Docker daemon is system-wide — directory
name prefixing is NOT sufficient for volume isolation.
Previous behaviour (e4063b5) COPY'd .bash_aliases and .inputrc
directly into /home/developer/ during image build. That silently
shadowed any host bind-mount or in-container customization for users
upgrading from v1.14.19b — if you'd written your own .bash_aliases
and rebuilt the container, our baked version would overwrite it
without warning.
Ship the files to /etc/skel-devbox/ instead. The entrypoint copies
them to $HOME only if the target file does not already exist, so:
- Fresh containers get the defaults automatically (unchanged)
- Host bind-mounts win (they materialize before the entrypoint runs)
- Existing in-container customizations survive upgrades
- Defaults remain discoverable at /etc/skel-devbox/ for anyone who
wants to copy, diff, or reset back to upstream
Docs (README.md, DOCKER_HUB.md, deploy/README.md) describe the new
skel layout and the restore/diff commands.
Two changes that address a longstanding frustration: bash history is
lost on every container recreate, and the container's ~/.bashrc and
~/.inputrc are stock Debian (no history tuning, no prefix search on
arrow keys, no integrations).
Added a named volume 'devbox-shell-history' mounted at ~/.cache/bash
with HISTFILE pointing there; history now survives 'docker compose up
--force-recreate'. The volume is added to both docker-compose.yml and
docker-compose.shared.yml, and ~/.cache/bash is registered in the
entrypoint ownership-fix loop per the AGENTS.md convention.
Baked rootfs/home/developer/.bash_aliases (sourced automatically by
Debian's default ~/.bashrc) and rootfs/home/developer/.inputrc into
the image. They give new containers: 100k-entry timestamped dedup
history with per-prompt flush, Up/Down arrow prefix history search,
case-insensitive coloured completion, aliases that prefer eza and
bat when present, git shortcuts, interactive rm/mv/cp, zoxide and
fzf (via 'fzf --bash') integration, and a [devbox] prompt marker.
The fzf integration uses 'fzf --bash' because we install fzf from
GitHub releases, not apt — the apt-path key-bindings aren't present.
Users who prefer their host's own shell config can uncomment two
commented bind-mount lines in docker-compose.yml to shadow the
baked defaults.
Two related documentation fixes for users mounting ~/.config/opencode
from the host:
1. Gate oh-my-opencode-slim references (file and agents) to the OMOS
variant in the Custom opencode config sections and data persistence
tables. Base-variant users no longer see oh-my-opencode-slim.json
listed as if it were always present.
2. Add a portability note warning that host-absolute paths in
opencode.json (e.g. file:///usr/local/lib/node_modules/... or
file:///opt/homebrew/...) will not resolve inside the Linux
container, and to prefer bare package specifiers that work on
both macOS and Linux hosts.
For machines where multiple users share one OS account. Each user gets
isolated containers, config, and named volumes by running docker compose
from their own directory with a unique SIGNUM in .env.
joakimp
pi
Joakim Persson
pi