opencode-devbox/AGENTS.md

AGENTS.md

Project overview

Docker image packaging opencode into a production-ready dev container. Image variants are published to Docker Hub via Gitea Actions CI. Not a library or application — this is infrastructure (Dockerfiles, entrypoint scripts, docker-compose, documentation).

File roles

• Dockerfile.base — variant-independent layers (apt, locales, AWS CLI, Node.js, mempalace, gitea-mcp, user setup, chromadb prewarm, ENVs, entrypoints). Published as joakimp/opencode-devbox:base-<sha12>. Rebuilt only when its content hash changes.
• Dockerfile.variant — FROMs the base and adds only opencode/omos/pi installs gated by build args: INSTALL_OPENCODE (default true), INSTALL_OMOS, INSTALL_PI, and INSTALL_MEMPALACE. All GitHub-sourced binaries are pinned with version ARGs.
• entrypoint.sh — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes (skipped via .devbox-owner sentinel when ownership is already correct). Then drops to developer via gosu. Volume ownership loop covers ~/.pi/ when INSTALL_PI=true.
• entrypoint-user.sh — runs as developer: git config, opencode.jsonc generation (delegated to generate-config.py), pi-toolkit + pi-extensions deploy (when pi installed), pi settings.json bootstrap, mempalace pi-bridge symlink, skillset auto-deploy from mounted skillset repo, OMOS setup.
• rootfs/usr/local/lib/opencode-devbox/generate-config.py — generates ~/.config/opencode/opencode.jsonc from env vars. Never overwrites an existing config (checks both .json and .jsonc). Auto-registers MCP servers for detected tools (mempalace via mempalace-mcp, gitea-mcp, context7 remote endpoint).
• scripts/smoke-test.sh — post-build image verification. Asserts binary presence, opencode startup, entrypoint correctness, config generation idempotency, and image size thresholds. Used by both CI workflows.
• scripts/generate-dockerhub-md.py — generates DOCKER_HUB.md from a hand-maintained HUB_TEMPLATE constant. --check fails if the committed file is out of sync (enforced by the validate workflow).
• DOCKER_HUB.md — auto-generated from HUB_TEMPLATE in scripts/generate-dockerhub-md.py. Do not edit directly. Pushed to Docker Hub description via CI API call. Must stay under 25 kB. Short description field must be ≤100 bytes.
• README.md — authoritative source documentation for everything in this repo. Independent of DOCKER_HUB.md: the Hub doc is hand-maintained in the generator's HUB_TEMPLATE and intentionally slim, linking back to the gitea README for depth.
• .gitea/README.md — read this first if you're touching CI. Architectural overview of the build pipeline (production vs split-base), wall-clock estimates, NPM_CONFIG_PREFIX gotcha, runner expectations, migration plan.
• .gitea/workflows/validate.yml — lightweight amd64 build + smoke test on push to main and PRs. Also runs the DOCKER_HUB.md sync check.
• .gitea/workflows/docker-publish-split.yml — production CI pipeline on tag push (v*). Two-phase split-base: computes base hash, conditionally builds base, runs 4 parallel smoke tests, then 4 parallel multi-arch variant builds, promotes base-latest alias, updates Docker Hub description.

Versioning scheme

Tags follow v{opencode_version}[letter] — e.g. v1.14.20 for the first build on a new opencode release, and v1.14.20b, v1.14.20c, … for subsequent rebuilds on the same opencode version.

• The number tracks the opencode npm version (see OPENCODE_VERSION ARG in Dockerfile.variant).
• No letter suffix on the first build of a new opencode version — the bare v{opencode_version} tag is the canonical release.
• Letter suffix is the build ordinal, starting at b for the second build. The letter a is never used — think of the suffix as counting rebuilds: b = 2nd, c = 3rd, d = 4th, …. For opencode version 1.14.20: first build v1.14.20, second v1.14.20b, third v1.14.20c, and so on.
• A letter suffix is only used for container-level rebuilds — tooling changes, CVE fixes, doc-driven rebuilds, entrypoint bugfixes — that don't change the underlying opencode version.

CI produces eight Docker Hub tags per release: vX.Y.Z[n], latest, vX.Y.Z[n]-omos, latest-omos, vX.Y.Z[n]-with-pi, latest-with-pi, vX.Y.Z[n]-omos-with-pi, latest-omos-with-pi — one tag pair (versioned + floating alias) per build variant.

When bumping the opencode version, bump OPENCODE_VERSION in Dockerfile.variant and update the comment in .env.example if it names a specific model/version for context.

Upstream sources — where to look up release notes

When drafting a release CHANGELOG entry, pull notes from the canonical upstream repo for each tracked package. Getting this wrong leads to thin or wrong release notes; the image bytes are unaffected but the documentation suffers.

Package	Canonical upstream	What you'll find there
opencode-ai (npm)	https://github.com/anomalyco/opencode/releases	Per-version release notes with Core / TUI / Desktop / SDK sections, contributor attributions. Some versions have empty bodies (internal/no-user-visible); most do not.
@earendil-works/pi-coding-agent (npm)	The CHANGELOG.md shipped inside the npm tarball: npm pack @earendil-works/pi-coding-agent@<version> then extract package/CHANGELOG.md.	Rich changelog with New Features / Added / Changed / Fixed sections per version.
Other floated tools (gosu, fzf, bat, eza, zoxide, uv, nvim, gitea-mcp, Go, oh-my-opencode-slim)	Each project's own GitHub releases page	Usually less material per release; quote selectively.

Trap to avoid: there is a github.com/sst/opencode repo that some search results surface; that's a fork (and probably the historical name people associate with opencode given the upstream lineage). It does NOT track the same release timeline. Use anomalyco/opencode for opencode release notes.

Fetch pattern (saved here for muscle memory):

# Latest stable opencode-ai versions on npm
npm view opencode-ai time --json | python3 -c 'import sys,json,re; d=json.load(sys.stdin); print(*sorted([(v,t) for v,t in d.items() if re.fullmatch(r"\d+\.\d+\.\d+",v)], key=lambda x:x[1], reverse=True)[:6], sep="\n")'

# Release notes for a specific version
curl -s https://api.github.com/repos/anomalyco/opencode/releases/tags/v1.15.10 | python3 -c 'import sys,json; print(json.load(sys.stdin).get("body","(empty)"))'

# pi changelog
cd /tmp && npm pack @earendil-works/pi-coding-agent@0.75.5 && tar -xzf earendil-works-pi-coding-agent-0.75.5.tgz package/CHANGELOG.md && head -40 package/CHANGELOG.md

Critical conventions

• entrypoint.sh volume ownership loop — when adding a new named volume mount point, add it to the for dir in ... loop in entrypoint.sh so root-owned volumes get chowned on startup. The loop writes a .devbox-owner sentinel after a successful chown so subsequent starts skip the recursive walk. Users should not touch these files.

• Documentation coupling on release — four docs co-vary and drift in lockstep when not updated together:

  • README.md is the source of truth for user-facing build/run/config detail.
  • DOCKER_HUB.md is auto-generated from HUB_TEMPLATE in scripts/generate-dockerhub-md.py. CI's --check run fails if it's stale. Hub-facing copy is intentionally slim (~5.5 kB, ~78% headroom against the 25 kB Hub limit) — update the template here when image variants, quick-start flow, or the elevator pitch change. README.md no longer feeds into Hub, so README edits do NOT require regenerating DOCKER_HUB.md.
  • CHANGELOG.md records every release. When cutting a tag, promote ## Unreleased to ## vX.Y.Z[n] — YYYY-MM-DD BEFORE pushing the tag so the tag points at a CHANGELOG that names itself. Keep entries reverse-chronological (newest at top, after the Unreleased block). Doc-only updates that happen post-tag (Hub description live-patches, README clarifications) get a fresh ## Unreleased block with a note that they don't trigger a new image build.
  • AGENTS.md (this file) carries domain facts that change on structural releases — tag-count statements, CI job lists, install contracts. After any change to .gitea/workflows/*.yml or the variant matrix, grep this file for stale numbers (grep -nE "four|eight|all [0-9]").
  • .env.example must be hand-updated to match Dockerfile/entrypoint behavior — it is not auto-generated.

  Release-day checklist: README → (regenerate DOCKER_HUB.md only if HUB_TEMPLATE changed) → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag.

  Between releases the same coupling applies. Doc drift is not just a release-day concern — a workflow tweak, entrypoint change, or generate-config.py refactor can leave any of these four files lying. Before committing a non-release change, grep the docs for references to what you touched: git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md DOCKER_HUB.md .gitea/README.md .env.example. If a doc says "four variants" / "two phases" / "runs on amd64 only" and your change made that no longer true, fix it in the same commit.

• GitHub/Gitea-sourced binaries float by default — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to latest. Each build-time install step reads the /releases/latest Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same ARCH case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: OPENCODE_VERSION (drives the image tag), NODE_VERSION=22 (major pin), DEBIAN_VERSION=trixie-slim (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag.

• Resolved versions are logged by the smoke test — scripts/smoke-test.sh prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to latest.

• PI_VERSION and OMOS_VERSION MUST be passed by CI as concrete versions, not left at the latest default. The npm install steps in Dockerfile.variant (npm install -g @earendil-works/pi-coding-agent / oh-my-opencode-slim@${OMOS_VERSION}) produce identical layer-hashes when the ARG values are byte-identical across builds; combined with the registry buildcache (base-buildcache) the layer gets reused even when latest would have resolved to a newer upstream. This is the same class of bug that bit pi-devbox v0.74.0 → v0.75.5 (silent same-bytes-across-releases regression discovered 2026-05-23, fixed in pi-devbox v0.75.5b). It is currently masked in opencode-devbox by OPENCODE_VERSION being a hard-coded ARG that bumps every release — that bump invalidates the parent-chain cache key for the downstream pi/omos layers — but the masking would fail the moment a vN.N.Nb opencode-version-unchanged release ships that only bumps pi or omos. Preventative fix: .gitea/workflows/docker-publish-split.yml has a resolve-versions job that runs npm view @earendil-works/pi-coding-agent version and npm view oh-my-opencode-slim version, exposing concrete values as outputs that every variant smoke + build job consumes via build-args. Smoke tests assert via EXPECTED_PI_VERSION / EXPECTED_OMOS_VERSION env vars — would catch the regression on the next release rather than four releases later. If you change the variant build-args list, the resolve-versions job, or the smoke EXPECTED_*_VERSION wiring, audit all affected jobs in lockstep.

• Shell scripts use set -euo pipefail — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with || true.

• MemPalace install path — installed via uv tool install into /opt/uv-tools/mempalace/. Both the mempalace CLI and the mempalace-mcp MCP server binary are shipped as entry points by the mempalace package itself and placed on PATH by uv as shims whose shebangs point at the venv's Python. No hand-rolled wrapper is needed. Do not use pip install --break-system-packages — that was the previous approach and has been removed. Do not use ["python3", "-m", "mempalace.mcp_server"] in opencode.jsonc — system Python can't import from the uv venv.

• generate-config.py idempotency — the script MUST never overwrite an existing opencode.jsonc or legacy opencode.json. Config persists in the devbox-opencode-config named volume; accidentally clobbering that file would destroy hand-edits. The smoke test asserts this.

• Skillset auto-deploy — on every container start, entrypoint-user.sh looks for a skillset repo (detection order: $SKILLSET_CONTAINER_PATH → $HOME/skillset → /workspace/skillset) and runs deploy-skills.sh --bootstrap --prune-stale. This creates relative symlinks in ~/.agents/skills/ and ~/.config/opencode/instructions/. Do NOT bind-mount ~/.agents/skills/ from the host — the container manages its own skills with relative symlinks that differ from the host's. The named volume devbox-opencode-config persists the deployed config across restarts.

• Config persistence via named volume — devbox-opencode-config is a Docker named volume mounted at ~/.config/opencode/. It is NOT a host bind mount by default. This separation allows both native and containerized opencode to coexist on the same machine without symlink conflicts. Users who need to override can replace the named volume with a host bind mount in their compose file. Same pattern for pi: devbox-pi-config is mounted at ~/.pi/ and persists user toggles (/ext-disabled extensions), ~/.pi/agent/settings.json edits, and — because NPM_CONFIG_PREFIX is set to ~/.pi/npm-global — anything installed via pi install npm:... or npm install -g as the developer user, across container recreate AND image rebuild.

• pi install contract — INSTALL_PI=true (default false) opt-in build arg. The baked pi binary is npm-installed globally to /usr at build time (system prefix). At runtime, NPM_CONFIG_PREFIX=/home/developer/.pi/npm-global is set in the image ENV with that prefix's bin/ prepended to PATH — so any pi install npm:... or npm install -g invoked by the developer user lands on the named volume and survives everything except docker compose down -v. The new ENVs are declared after all build-time npm install -g calls in the Dockerfile so they don't redirect the baked installs into a path that the volume mount would later shadow. If the user runs npm install -g @earendil-works/pi-coding-agent themselves, the user-installed copy on the volume wins via PATH order; otherwise image rebuild is the upgrade path for the baked pi (same contract as OPENCODE_VERSION). The pi-toolkit and pi-extensions repos are git-cloned into /opt/ at build time, then their install.sh runs from entrypoint-user.sh on each container start to symlink into ~/.pi/agent/ (which lives on the named volume). The mempalace pi-bridge is symlinked manually from /opt/mempalace-toolkit/extensions/pi/mempalace.ts — we do NOT call mempalace-toolkit's full install.sh because its install_skill step would race with skillset auto-deploy --prune-stale.

• Pi deploy ordering matters in entrypoint-user.sh — pi-toolkit runs first (creates keybindings.json symlink and writes pi-env.zsh), then pi-extensions, then settings.json template bootstrap, then mempalace bridge symlink. mempalace-toolkit's check_pi_toolkit probe (when called from the host install path) expects keybindings to already be present — not currently called from container, but ordering matches host convention.

• Default CMD is bash -l — not a harness. docker compose run --rm devbox drops the user into a login shell to choose: aws sso login, then opencode or pi (or any tool). Pass the harness explicitly to launch directly: docker compose run --rm devbox opencode / docker compose run --rm devbox pi. docker compose exec bypasses entrypoint+CMD entirely (existing user workflow unchanged).

• Docker Hub description update — uses /v2/auth/token endpoint (not the deprecated /v2/users/login). Auth uses identifier/secret fields, returns access_token, sent as Bearer. Short description must be ≤100 bytes.

CI quirks

• Both build jobs include an IPv4 preference step (gai.conf + driver-opts: network=host for buildx) to work around intermittent IPv6 failures on the Gitea runners.
• update-description job runs only when both builds succeed (needs: [build-base, build-omos]).
• Tags must be pushed to trigger the publish workflow. The validate workflow runs on push to main and PRs.
• Smoke tests run on amd64 only (single-arch load into the local daemon). The multi-arch push happens after smoke passes.
• Gitea Actions runner has ~40 GB disk, often 70%+ used at job start. All eight load: true jobs (validate-base, validate-omos, validate-with-pi, validate-omos-with-pi, smoke-base, smoke-omos, smoke-with-pi, smoke-omos-with-pi) include a Reclaim runner disk step that strips catthehacker-resident toolchains and prunes stale docker state before setup-buildx-action. Build jobs use a lighter version (push-by-digest doesn't need docker system prune). Don't remove these steps without testing on a fresh runner.
• docker/build-push-action@v7 with platforms: linux/amd64,linux/arm64 handles multi-arch push natively in a single job — produces a proper manifest list, no matrix or merge step needed. An earlier revision split into per-arch matrix jobs with digest artifacts, but that pattern requires actions/{upload,download}-artifact@v4+ which Gitea Actions doesn't support (see below).
• actions/upload-artifact and actions/download-artifact must stay at @v3 on Gitea. v4+ uses a GitHub-Enterprise-specific Artifact API; runs fail with GHESNotSupportedError. If you need artifacts for a new reason (build logs, SBOMs, etc.), pin @v3 explicitly.
• Step scripts run under /bin/sh (dash), not bash. Avoid bash-isms like ${VAR//a/b} parameter-pattern substitution; use POSIX alternatives (tr, sed) or declare shell: bash on the step.
• BUILDKIT_PROGRESS=plain is set at workflow level on docker-publish-split.yml so arm64-under-QEMU builds log each layer line-by-line. The default collapsed progress UI hides which step is stalled, which made diagnosing earlier hangs expensive.

Testing changes

The smoke test (scripts/smoke-test.sh) is the canonical check and runs automatically in CI. To run locally:

# Base image
docker compose build
bash scripts/smoke-test.sh opencode-devbox --variant base

# OMOS image
docker build --build-arg INSTALL_OMOS=true -t opencode-devbox:omos .
bash scripts/smoke-test.sh opencode-devbox:omos --variant omos

For manual/exploratory testing:

1. docker compose run --rm devbox bash
2. Check specific tools inside: nvim --version, bat --version, uv --version, mempalace --help, etc.
3. For entrypoint changes: test with a non-1000 UID workspace to verify UID adjustment, volume ownership fixes, and the .devbox-owner sentinel behavior.
4. For generate-config.py changes: run standalone with HOME=/tmp/fake OPENCODE_PROVIDER=anthropic python3 rootfs/usr/local/lib/opencode-devbox/generate-config.py.

Commit style

Imperative mood, first line summarizes the change. Multi-line body explains "why" when non-obvious. Examples from history:

• Fix ownership of named volume mount points in entrypoint
• Add uv package manager to base image for on-demand Python support
• Upgrade base image from Debian bookworm to trixie (current stable)