Joakim Persson
cb6d9e5dd0
The two most recent Unreleased entries (pi-extensions 25c1265: task tool +
fork-gate; mempalace-toolkit 817b3a8: the mine deadline that never reached
the transport) reached this image through floating *_REF=main ARGs. Neither
produced a diff here, so nothing asked for a CHANGELOG line, and neither had
one until a reader asked. Same class as check 8 — a claim with no in-repo
anchor rots — and the hand practice that covered it (the per-release
"Dependency audit" table, Baked-in vs Upstream-now) is a someone-remembers
mechanism that had lapsed.
Method, no docker/crane/token: last published vX.Y.Z from Hub's tag list
(one request, now shared with check 8); its amd64 config blob via the
anonymous registry API carries one se.jordbo.pi-devbox.<name>-ref label per
component with the SHA the build-args baked. "Would bake" is resolved the way
resolve-versions does it: 40-hex ARG is itself, branch/tag via git ls-remote
with the peeled ^{} form preferred, pi-studio = highest semver tag (label on
<tag>-studio), PI_VERSION as a literal against the pi-version label. Nine
components, ~7.5 s. Unchanged: OK. Moved: the new value's 7-char prefix (tag
for studio, version for pi) must appear above the last published version's
"## " heading — Unreleased plus any not-yet-published section, which is what
the release commit turns Unreleased into, so the tag build passes on the same
text. A published tag with no heading is a failure, not a skip.
First run found a move nobody had recorded: pi-observational-memory 7b397f4
-> cba0334 (6 commits, 3.1.1 -> 3.1.3; memory workers now routed by the
model's exact provider instead of the first registered provider with a
matching api — upstream #70). Named in the CHANGELOG with the honest scope:
no expected effect on the shipped bedrock-only configuration, unmeasured.
Sabotage-tested, expectation written before each run:
obsmem SHA removed from CHANGELOG ............ rc=1 DRIFT
Unreleased renamed to "## v1.9.3 — …" ........ rc=0 (release-commit shape)
"## v1.9.2" heading mangled to v1.9.2-typo .... rc=1 — this one FAILED first:
\b accepted "v1.9.2-typo" as v1.9.2's heading; now (\s|$)
bare "## v1.9.2" (no date) ................... rc=0
ARG PI_OBSMEM_REPO renamed ................... rc=2 (blind gate must not pass;
read_arg calls are bare top-level assignments on purpose — nested in a
heredoc's $(...) the exit 2 is swallowed by cat)
offline (proxy to a closed port) ............. rc=0, 2 SKIPs counted
SKIP_REF_CHECK=1 ............................. rc=0, 1 SKIP counted
restored ..................................... rc=0, files byte-identical
GIT_TERMINAL_PROMPT=0 on ls-remote: a repo flipped private fails in 0.3 s as
a SKIP instead of waiting for a username until the job times out.
Header, lint.yml job comment and AGENTS.md all still said this gate "needs
no network" — false since check 8 (2026-09-14). Now: two classes, hermetic
1-7 and published-state 8-9 that SKIP loudly and counted when offline.
Considered and not added: compose <-> .env.example variable cross-check (the
four mismatches are commented-out lines, the mempalace-server compose file's
own variables, and entrypoint-consumed ones — it would fire on nothing
wrong); "documented tag exists on Hub" (check 8 already SKIPs by name; a
hard fail would misreport the tag-to-publish window).
385 lines
22 KiB
Markdown
385 lines
22 KiB
Markdown
# AGENTS.md — pi-devbox
|
||
|
||
Self-contained Docker image for the **pi coding-agent**. Decoupled from
|
||
opencode-devbox at v1.0.0 (2026-06-09); previously pi-devbox was a thin
|
||
re-brand of opencode-devbox's `pi-only` variant.
|
||
|
||
## Repository layout
|
||
|
||
- `Dockerfile.base` — multi-arch base layer with system packages,
|
||
GitHub-binary tools (fzf, eza, zoxide, neovim, bat, gosu, gitleaks,
|
||
git-lfs, uv, gitea-mcp, tealdeer), AWS CLI v2, mempalace + toolkit,
|
||
Node.js, Python toolchain, locales, ssh ControlMaster defaults, and
|
||
`/etc/tmux.conf` with 0-indexed sessions.
|
||
- `Dockerfile.variant` — `FROM base-<hash>`, adds pi + companions
|
||
(`pi-toolkit`, `pi-extensions`, `pi-fork`, `pi-observational-memory`)
|
||
and, when `INSTALL_STUDIO=true`, vendors `pi-studio` to `/opt/pi-studio`
|
||
(`-studio` variant). Also appends the pi-devbox managed block from
|
||
`pi-global-AGENTS.append.md` onto pi-toolkit's `pi-global-AGENTS.md` (the
|
||
single global instruction slot pi loads) so containers proactively load the
|
||
baked `pi-devbox-environment` skill. Idempotent via a marker grep. After the
|
||
pinned clones it also refreshes the vendored `pi-extensions` fallback skill
|
||
by copying `/opt/pi-extensions/skill/` over the committed `rootfs/` snapshot
|
||
(Option 1 over Option 2 — see `skills/VENDORED.md`).
|
||
- `entrypoint.sh` — UID/GID alignment as root, then drops to `developer`.
|
||
- `entrypoint-user.sh` — per-container start: prints the `pi-devbox-version`
|
||
banner first (which build/commit is running, from the manifest below),
|
||
then SSH ControlMaster socket dir, LAN-access setup, MemPalace init,
|
||
pi-toolkit + pi-extensions deploy, mempalace-bridge symlink, fork/recall +
|
||
pi-studio pi-install, optional `studio-expose` bridge (when
|
||
`STUDIO_EXPOSE=1`), image-baked skills symlink-in, skillset deploy.
|
||
- `rootfs/` — files baked into the image (bash aliases, inputrc,
|
||
setup-lan-access.sh, `studio-expose` helper, `pi-devbox-version` — wraps
|
||
`/etc/pi-devbox/build-manifest.json` into a human-readable summary + live
|
||
drift check, see README “Build provenance”). Also
|
||
`usr/local/share/pi-devbox/skills/<name>/SKILL.md` — image-baked agent
|
||
skills (the repo-authored `pi-devbox-environment`, plus vendored fallback
|
||
copies of `pi-extensions` and `mempalace` — see `skills/VENDORED.md`)
|
||
symlinked into `~/.agents/skills/` by the entrypoint, available with or
|
||
without a mounted skillset — plus
|
||
`usr/local/share/pi-devbox/pi-global-AGENTS.append.md` (the global-AGENTS
|
||
pointer concatenated in `Dockerfile.variant`).
|
||
- `scripts/smoke-test.sh` — sanity checks run by CI before pushing to Hub.
|
||
- `.gitea/workflows/docker-publish.yml` — two-phase CI (base-decide →
|
||
build-base → smoke → build-variant → promote-base-latest →
|
||
update-description). The `-studio` variant adds independent
|
||
`smoke-studio` + `build-variant-studio` jobs that gate only the
|
||
`-studio` tags (never the core `:latest` release).
|
||
|
||
## Versioning scheme
|
||
|
||
- Tags follow semver. **v1.0.0** is the first decoupled release; future
|
||
minor bumps add variants (`-studio`, `-studio-tex`) or significant base
|
||
additions (e.g. v1.2.0 image-baked agent skills); patch bumps follow
|
||
pi npm version updates and small fixes.
|
||
- Docker Hub tags: `joakimp/pi-devbox:vX.Y.Z` + `joakimp/pi-devbox:latest`
|
||
+ (since v1.1.0) `joakimp/pi-devbox:vX.Y.Z-studio` +
|
||
`joakimp/pi-devbox:latest-studio`.
|
||
Internal tags: `joakimp/pi-devbox:base-<hash>` (content-addressed) +
|
||
`joakimp/pi-devbox:base-latest` (alias of most recent base).
|
||
|
||
## Release-day checklist
|
||
|
||
1. Confirm `pi --version` resolves from npm to the expected version
|
||
(`curl -sf 'https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest' | jq -r .version`).
|
||
Check release notes at https://github.com/earendil-works/pi/releases for
|
||
the upstream changelog to include in `CHANGELOG.md`.
|
||
2. **Refresh the vendored mempalace skill snapshot if the skillset moved:**
|
||
`scripts/vendor-mempalace-skill.sh --check` (reads a real skillset clone,
|
||
writes nothing). Three exit codes, not two — a stale-but-truthful record is
|
||
**not** a release blocker, so don't treat any non-zero exit as "must
|
||
refresh" without reading which one it was:
|
||
- **0** — the record is truthful. This includes stale-but-truthful
|
||
(upstream has moved past the recorded ref, or the local clone has
|
||
uncommitted changes) — a `NOTICE` is printed, but nothing is lying.
|
||
**Skipping the refresh in this case is the legitimate, sanctioned
|
||
outcome** — every enrolled host reads its own live skillset clone, so
|
||
the baked copy is only a no-mount fallback. What is not legitimate is
|
||
skipping it *silently*: the drift is visible here, in
|
||
`pi-devbox-version`, and in the manifest, so decide rather than forget.
|
||
- **1** — a confirmed problem: the vendored bytes provably do NOT match
|
||
the file at the recorded ref (a lying record), or the recorded ref
|
||
doesn't even resolve to that path in this clone. Refresh.
|
||
- **2** — cannot determine (the recorded ref itself isn't resolvable in
|
||
this clone — commonly a shallow checkout missing history). Fetch full
|
||
history and re-check before deciding; don't refresh blind.
|
||
Refresh with `scripts/vendor-mempalace-skill.sh`, which rewrites the file
|
||
**and** the ARG together so they cannot drift apart, and refuses (exit 1)
|
||
rather than silently rewinding provenance if the skillset clone's HEAD is
|
||
behind the already-recorded ref (detached HEAD, older checkout) — pass
|
||
`--force` only if that rewind is genuinely intended.
|
||
Two consequences to accept deliberately on an actual refresh: the snapshot
|
||
is hashed into `base_tag`, so it costs a base rebuild (~67 min); and if the
|
||
section the phrase canary names has changed, re-pin it in
|
||
`scripts/smoke-test.sh`.
|
||
3. **Update the docs this release makes stale — BEFORE you tag.** Rename
|
||
`CHANGELOG.md`'s `## Unreleased` to `## vX.Y.Z — YYYY-MM-DD` (em dash, as
|
||
every prior release heading uses), then run the gate:
|
||
|
||
```bash
|
||
bash scripts/check-doc-drift.sh # 0 in sync / 1 drift / 2 cannot run
|
||
```
|
||
|
||
It compares README.md's version-pin table against the ARGs it names, and
|
||
DOCKER_HUB.md's Node claim against `ARG NODE_VERSION`, plus Hub's
|
||
25 000-char limit, unsubstituted `{{PLACEHOLDERS}}`, and stale `Unreleased`
|
||
pointers in user-facing docs. With network it also checks DOCKER_HUB.md's
|
||
size claims against Hub's measured sizes (check 8) and — check 9 — that
|
||
**every component the next build would bake differently from the last
|
||
published release is named in the CHANGELOG** above that release's heading:
|
||
it reads the `se.jordbo.pi-devbox.*-ref` labels off the published image and
|
||
`git ls-remote`s each floating `*_REF`. A red check 9 means an upstream
|
||
(pi-toolkit, pi-extensions, mempalace-toolkit, pi-fork,
|
||
pi-observational-memory, pi-studio) moved and no entry names the new SHA;
|
||
the failure prints the compare URL. Name the 7-char SHA where you describe
|
||
the change — that is what the old "Dependency audit" tables recorded by
|
||
hand, now required.
|
||
|
||
**Why before and not after:** `docker-publish.yml` runs `actions/checkout@v4`
|
||
with no `ref:`, so every job reads `github.ref` — the **tag**. A doc fix
|
||
pushed to `main` after tagging does not reach the release, and for
|
||
`DOCKER_HUB.md` it does not reach the published Hub page either, because
|
||
`update-description` POSTs that file as Docker Hub's `full_description` from
|
||
the tag's tree. Getting it in afterwards means re-pointing the tag, which is
|
||
its own hazard (v1.8.14 went `601fc98` → `361babd` and broke deploy
|
||
verification until `git fetch --tags --force`).
|
||
|
||
The gate is deliberately narrow — it only checks claims verifiable from files
|
||
in this repo. Still eyeball, because these are NOT gated:
|
||
- counts and sizes (`~1.1 GB`, "N `mempalace_*` tools", "7 extensions") —
|
||
they need a running image; assert them in `scripts/smoke-test.sh` instead
|
||
- feature prose that quietly became false, e.g. a "Planned for an upcoming
|
||
release" section describing something that already shipped
|
||
- `Dockerfile.base`'s `# BASE_REBUILD_DATE:` marker. Ungated on purpose:
|
||
`base_tag` hashes Dockerfile.base's content, comments included, so
|
||
demanding it be current would force a ~60 min base rebuild on a release
|
||
that touched no base files. **Fix it when the base is already rebuilding —
|
||
then it is free.**
|
||
|
||
Measured cost of skipping this, 2026-09-10 (v1.9.0): five stale claims, one
|
||
of them published. README's pin table was wrong on all three rows, and
|
||
DOCKER_HUB.md — untouched for eight releases — still said Node v22 while the
|
||
image shipped Node 24.
|
||
4. Verify `docker compose up` works locally with the current `latest` image
|
||
if you're upgrading users from a previous version. Then run the
|
||
**post-recreate sanity check** inside the running container to confirm
|
||
persisted volumes survived and the pi runtime wiring re-deployed (not just
|
||
that the container booted):
|
||
`docker compose exec devbox bash scripts/recreate-sanity-check.sh --expected-image-version X.Y.Z`
|
||
(or just `pi-devbox-sanity --expected-image-version X.Y.Z` if
|
||
`cli_utils/bin` is on PATH). This is the runtime peer of the build-time
|
||
`smoke-test.sh` gate.
|
||
**`X.Y.Z` here is the pi-devbox release tag** you are shipping (e.g.
|
||
`1.8.9`), which is what the rest of this checklist means by `vX.Y.Z`.
|
||
`--expected-image-version` is the flag that asserts it. There is also an
|
||
`--expected-version`, and it means something else — the **pi coding agent**
|
||
version (e.g. `0.84.3`, the `ARG PI_VERSION` pin). Handing the release tag
|
||
to that one used to report *"pi version mismatch: expected 1.8.8, got
|
||
0.84.3"*, i.e. a red on the final gate of the release accusing the wrong
|
||
component; it now tells you to use `--expected-image-version` instead, and
|
||
the reverse mix-up is caught too. Both flags are optional — with neither,
|
||
the live pi version is asserted against the version recorded in the image's
|
||
own build manifest (which catches a stale `pi` in the `~/.pi/npm-global`
|
||
volume shadowing the baked one) and the image tag is reported
|
||
informationally.
|
||
5. Push tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
|
||
6. Watch CI: smoke job builds amd64 only and asserts size + extensions +
|
||
pi version + new-base-tooling presence. Variant build is multi-arch
|
||
(amd64 + arm64) only after smoke passes. A tag push fires **only**
|
||
`docker-publish.yml` — `lint.yml` is scoped to `branches: ['**']`, which
|
||
excludes tag refs on purpose (the tagged tree was already linted when the
|
||
commit hit `main`, and a fast lint run sorting above the slow publish run
|
||
made releases look finished before anything shipped). Verified on v1.8.4:
|
||
`refs/tags/v1.8.4` produced run 571 (publish) and nothing else. Still filter
|
||
discovery on `head_sha` **and** the workflow `path` — see *Gitea API access*
|
||
below — because that guard costs nothing and a future workflow added on `v*`
|
||
would silently reintroduce the ambiguity.
|
||
7. Verify the Hub tags appear (latest + vX.Y.Z, the `-studio` pair, plus
|
||
base-latest if the base was rebuilt this run).
|
||
8. **Revoke any short-lived Gitea PAT** used during the release at
|
||
`gitea.jordbo.se/user/settings/applications`. N/A if you used the
|
||
`GITEA_ACCESS_TOKEN` env var instead (see *Gitea API access* below) —
|
||
its lifecycle is managed host-side, nothing to revoke.
|
||
|
||
## Verifying this repo's reality from inside a container
|
||
|
||
Most work on this repo happens **inside** a pi-devbox container, inspecting a
|
||
host or a peer over SSH. That setup manufactures convincing false negatives, so
|
||
when you are about to report that something is **absent, unreachable, or not
|
||
running**, suspect your own command first. Recurring instances:
|
||
|
||
- **`docker` is not on the host's non-interactive SSH `PATH`.** `ssh mac 'docker
|
||
ps'` says *command not found* on a host that plainly runs Docker; use
|
||
`/usr/local/bin/docker` (or `command -v docker` first). Every step in the
|
||
*Release-day checklist* that inspects a running container hits this.
|
||
- **Don't `| head -N` a search whose answer you don't already know.** The host's
|
||
`~/.ssh/config` is ~500 lines; a `head -20` "proved" a peer absent that was
|
||
defined at line 454.
|
||
- **The deployment compose file is not this repo's.** `docker-compose.yml` here
|
||
is a template pinning `:latest`; a real host runs its own per-machine file
|
||
(find it with `docker inspect <container> --format '{{ index .Config.Labels
|
||
"com.docker.compose.project.config_files" }}'`). Recreating from the repo copy
|
||
can silently move a host off `:latest-studio` onto `:latest`.
|
||
- **A live SSH ControlMaster hides remote auth changes** — after editing a
|
||
peer's `authorized_keys`, prove access with `-o ControlPath=none -o
|
||
ControlMaster=no`, or the breakage surfaces in a later session instead.
|
||
|
||
Depth and further mechanisms: the repo-authored `pi-devbox-environment` skill
|
||
(`rootfs/usr/local/share/pi-devbox/skills/pi-devbox-environment/SKILL.md`) §2
|
||
and §3 — that file is the one an agent actually loads mid-session, whereas this
|
||
`AGENTS.md` is only auto-read when the cwd *is* this repo.
|
||
|
||
## Gitea API access (env token)
|
||
|
||
`GITEA_ACCESS_TOKEN` + `GITEA_HOST` are passed into the container from the
|
||
host `.env` via `docker-compose.yml` (`${GITEA_ACCESS_TOKEN:-}` /
|
||
`${GITEA_HOST:-}`), primarily to enable the `gitea-mcp` server. They are
|
||
**not** baked into the image. When configured, they are also available for
|
||
**any** direct Gitea API interaction from inside the container — inspecting
|
||
CI runs, checking published tags, listing commits — e.g.
|
||
`curl -H "Authorization: token $GITEA_ACCESS_TOKEN" "$GITEA_HOST/api/v1/repos/joakimp/pi-devbox/actions/runs?limit=20"`.
|
||
Prefer this over a short-lived PAT file when the env token is present (the
|
||
`ci-release-watcher` skill auto-detects it). Public-repo GET listings work
|
||
unauthenticated too, so the token matters mainly for private repos or
|
||
rate-limit headroom; its lifecycle is host-managed, so there is nothing to
|
||
revoke after use. Never echo the token value (including into logs).
|
||
|
||
**Gotcha — a tag push fires EVERY workflow whose triggers match the tag ref.**
|
||
`lint.yml` uses a bare `push:` trigger, so a release tag yields *both* a lint run
|
||
and the publish run. The listing is newest-first and lint sorts **above** the
|
||
publish run, so "take the first run whose `path` contains `refs/tags/<tag>`"
|
||
picks the wrong one **reliably, not occasionally**. Real listing for v1.6.4:
|
||
|
||
```
|
||
id=531 #104 lint.yml@refs/tags/v1.6.4 <- wrong; sorts first
|
||
id=530 #103 docker-publish.yml@refs/tags/v1.6.4 <- the release build
|
||
id=529 #102 lint.yml@refs/heads/main <- same commit, linted on push
|
||
```
|
||
|
||
Lint goes green in minutes while the image is still building, so watching it
|
||
makes a release look finished when nothing has been published yet.
|
||
|
||
**Gotcha — the jobs endpoint takes the internal `id`, NOT the `run_number` the
|
||
UI shows as `#104`.** The two diverge widely, and `GET
|
||
.../actions/runs/<run_number>/jobs` does **not** error — it silently returns a
|
||
*different* run's jobs. Always read `id` from the run listing:
|
||
|
||
```bash
|
||
# Which runs did this tag/commit trigger? Filter on head_sha; never trust
|
||
# ordering or run numbering. limit=20, not 5 — with two runs per push the
|
||
# publish run falls off a 5-item window fast.
|
||
curl -sS -H "Authorization: token $GITEA_ACCESS_TOKEN" \
|
||
"$GITEA_HOST/api/v1/repos/joakimp/pi-devbox/actions/runs?limit=20" \
|
||
| jq --arg sha "$(git rev-list -n1 vX.Y.Z)" \
|
||
'.workflow_runs[] | select(.head_sha==$sha) | {id, run_number, path, status, conclusion}'
|
||
# pick the id whose .path starts with docker-publish.yml, then:
|
||
curl -sS -H "Authorization: token $GITEA_ACCESS_TOKEN" \
|
||
"$GITEA_HOST/api/v1/repos/joakimp/pi-devbox/actions/runs/<id>/jobs" \
|
||
| jq '.jobs[] | {name, status, conclusion}'
|
||
```
|
||
|
||
**Watcher config for this repo** (`ci-release-watcher` skill, hub-only shape —
|
||
pi-devbox has no downstream host to deploy to):
|
||
|
||
- `EXPECT_WORKFLOW=docker-publish.yml` — the skill's `preflight_run()` aborts at
|
||
startup if the run id belongs to lint instead.
|
||
- `EXPECTED_FRESH_TAGS='vX.Y.Z latest vX.Y.Z-studio latest-studio'`
|
||
- `EXPECTED_EXISTS_TAGS='base-latest'` — existence only: it is content-addressed
|
||
and legitimately keeps its old timestamp when the base is a cache hit.
|
||
- `CRITICAL_JOBS='build-variant build-variant-studio'` — job names are matched
|
||
**exactly** (`critical.issubset(succeeded)`), so the studio variant must be
|
||
listed explicitly; the skill's default omits it. Leave `promote-base-latest`
|
||
out: it legitimately skips on a base cache hit, which would misclassify a good
|
||
run. `update-description` is the cosmetic post-publish job.
|
||
|
||
## Cache-hit footgun (must-know)
|
||
|
||
`PI_VERSION` defaults to `latest` in `Dockerfile.variant` but **CI must
|
||
resolve it to a concrete version string** before passing as a build-arg.
|
||
Otherwise the build-arg string is byte-identical across releases →
|
||
identical layer hash → registry buildcache silently reuses the old
|
||
layer. `resolve-versions` job in the workflow handles this.
|
||
|
||
Discovered in pi-devbox 2026-05-23 (every release v0.74.0..v0.75.5
|
||
shipped the same image bytes); preventatively fixed for `PI_VERSION` +
|
||
`PI_FORK_REF` + `PI_OBSMEM_REF`.
|
||
|
||
## Smoke-test gate
|
||
|
||
`scripts/smoke-test.sh` runs amd64-only against a freshly-built variant
|
||
image. Verifies binaries, repo clones, runtime deployment (waits for
|
||
keybindings + mempalace bridge + ≥4 extensions before sampling — fixes
|
||
the parallel-build-load race documented in opencode-devbox c6f9d11
|
||
2026-06-08), build-time leftovers (see below), and image size threshold
|
||
(3800 MB in `SIZE_THRESHOLD_MB`; revisit after a few releases as actuals
|
||
settle — this doc said 3500 until 2026-09-11, after the bar had already
|
||
moved twice).
|
||
|
||
If smoke fails on size threshold but build is otherwise fine: bump
|
||
`SIZE_THRESHOLD_MB` in scripts/smoke-test.sh in a follow-up commit and
|
||
re-run. The threshold exists to catch *runaway* growth (an accidental
|
||
texlive bake-in, a forgotten chrome dependency), not to block ordinary
|
||
upstream bumps.
|
||
|
||
**The size gate is not a substitute for naming the residue.** It carries
|
||
~225 MB of deliberate margin, so v1.9.1 shipped +131 MB of pure build
|
||
residue — 110 MB of it npm's own download cache under `/root/.npm`, the
|
||
rest foreign platform packages — and stayed green. Four named assertions
|
||
now cover that ground: no foreign npm-11 platform packages beyond the
|
||
host arch (`@esbuild/*`, `@mariozechner/clipboard-*`), no `/root/.npm` in
|
||
the image, and — because the prune's real risk is *removing something
|
||
needed*, not size — esbuild must compile TS and clipboard must load its
|
||
native binding at **every** install site.
|
||
|
||
Two failure shapes to copy from those, both of which bit here:
|
||
- `test ! -d /root/.npm` on mode-700 `/root` passes for a **permission**
|
||
error, so the cache assertion refuses to run as non-root. Watch for
|
||
this in any assertion about a path you may not be allowed to read.
|
||
- `node -e 'require("esbuild")'` resolves by walking up from the CURRENT
|
||
DIRECTORY, so it fails with `MODULE_NOT_FOUND` from `/workspace` on a
|
||
perfectly healthy image (esbuild is nested inside the pi trees;
|
||
`NODE_PATH` is unset). Always path-qualify: `require("<abs>/esbuild")`.
|
||
A runbook shipped the bare form with "if this fails, revert the
|
||
release" attached, and it duly went red for the wrong reason.
|
||
|
||
## Build pipeline notes
|
||
|
||
- **Two-phase**: base + variant. Base is rebuilt only when
|
||
`Dockerfile.base`, `rootfs/`, or `entrypoint*.sh` change (CI computes
|
||
a content hash and probes Hub for an existing `base-<hash>` tag).
|
||
- **`base-latest` alias** is promoted from `base-<hash>` via `crane copy`
|
||
(manifest copy, no rebuild) only when the base actually changed.
|
||
- **`docker buildx build --push` retry**: 3 attempts with backoff for
|
||
transient Hub blips. Deterministic failures fail all 3 and the job
|
||
fails as expected.
|
||
- **Registry buildcache disabled**: buildkit's cache-export hits HTTP 400
|
||
on Hub CDN since ~2026-05-23. Image push works fine; we pay the full
|
||
base build on Dockerfile.base change, but base tags are content-
|
||
addressed so unchanged bases short-circuit at the probe step.
|
||
|
||
## Decoupling history (briefly)
|
||
|
||
Pre-v1.0.0 pi-devbox was `FROM joakimp/pi-devbox:base-pi-only`, where
|
||
`base-pi-only` was a tag built by **opencode-devbox CI** (with
|
||
`INSTALL_OPENCODE=false` in their variant Dockerfile) and pushed under
|
||
the pi-devbox repo as an internal building-block tag. This setup
|
||
required rebuilding opencode-devbox before pi-devbox could be tagged
|
||
and meant pi-devbox docs needed cross-referencing into opencode-devbox.
|
||
|
||
v1.0.0 brings pi install logic into this repo, drops the cross-repo
|
||
dependency, and the `base-pi-only*` tags from opencode-devbox become
|
||
deprecated artifacts (to be removed in opencode-devbox v2.0.0).
|
||
|
||
## What we DON'T install (and why)
|
||
|
||
- **No texlive** (~600 MB–1 GB). PDF export from pandoc / pi-studio works
|
||
out of the box via **`typst`** (~30 MB static binary), which the base ships
|
||
as the pandoc PDF engine (`pandoc --pdf-engine=typst`) — small enough to live
|
||
in base rather than a dedicated `:latest-studio-tex` variant. We don't bake in
|
||
a full TeX Live: it's heavy and typst covers the common Markdown→PDF case.
|
||
Users needing LaTeX-exact output can install the higher-fidelity fallback on
|
||
demand: `sudo apt-get install texlive-xetex texlive-latex-recommended` (then
|
||
`pandoc --pdf-engine=xelatex`).
|
||
- **pi-studio** ships in the `:latest-studio` variant (since v1.1.0),
|
||
vendored to `/opt/pi-studio` and registered at container start via
|
||
`pi install /opt/pi-studio` (see Dockerfile.variant `INSTALL_STUDIO`).
|
||
The default `:latest` image stays studio-free. Note: pi-studio binds
|
||
`127.0.0.1` inside the container, so browser access needs host
|
||
networking or the bundled `studio-expose` bridge (socat; auto-starts
|
||
when `STUDIO_EXPOSE=1`) — see README "Using pi-studio".
|
||
- **No Julia/R/GHCi/Clojure runtimes**. Use `uv run --with X` for
|
||
Python REPLs; `apt install` other-language runtimes ad-hoc per
|
||
container if needed.
|
||
|
||
## Backward compatibility
|
||
|
||
- The host `~/.mempalace` bind-mount path is unchanged.
|
||
- Volume names (`devbox-pi-config`, `devbox-ssh-local`,
|
||
`devbox-shell-history`, `devbox-zoxide`, `devbox-nvim-data`,
|
||
`devbox-uv`; optional `devbox-palace`, `devbox-chroma-cache`) are
|
||
unchanged.
|
||
- `~/.pi/agent/` layout inside the container is unchanged; existing
|
||
named volumes work without recreation.
|
||
- The `:latest` and `vX.Y.Z` Hub tags continue to point at a "base + pi"
|
||
image. Same tag, same shape, just built differently.
|