diff --git a/.github/workflows/pr-test.yml b/.github/workflows/pr-test.yml
index 212f519..29cc9d6 100644
--- a/.github/workflows/pr-test.yml
+++ b/.github/workflows/pr-test.yml
@@ -14,8 +14,8 @@ jobs:
steps:
- uses: actions/checkout@v4
- uses: arduino/setup-task@v2
- - run: python3 test-release-automation.py
- - run: bash test-bump-version.sh
+ - run: python3 tests/test-release-automation.py
+ - run: bash tests/test-bump-version.sh
test:
name: Runtime behavior tests (${{ matrix.track }})
@@ -77,13 +77,16 @@ jobs:
IN="docker run --rm -e GITHUB_TOKEN --entrypoint bash opencode-test:latest"
test "server entrypoint, authentication, and flags work in the real image" \
- "bash test-server-e2e.sh opencode-test:latest"
+ "bash tests/test-server-e2e.sh opencode-test:latest"
test "home-tool installer works in the real image" \
- "bash test-home-tools-e2e.sh opencode-test:latest"
+ "bash tests/test-home-tools-e2e.sh opencode-test:latest"
test "package managers and zerobrew-backed lazy tools work in the real image" \
- "bash test-toolchain-e2e.sh opencode-test:latest"
+ "bash tests/test-toolchain-e2e.sh opencode-test:latest"
+
+ test "locked tools install without version lookups; user tools resolve latest" \
+ "bash tests/test-mise-lock-e2e.sh opencode-test:latest"
echo "=== Pre-installed tools (interactive) ==="
@@ -137,6 +140,9 @@ jobs:
test "npx resolves from auto-install-shims" \
"$IN -c 'which npx | grep -q /opt/auto-install-shims/npx'"
+ test "clonetree, codex, claude, and cloudflared resolve from auto-install-shims" \
+ "$IN -c 'for c in clonetree codex claude cloudflared; do which \$c | grep -q /opt/auto-install-shims/\$c || exit 1; done'"
+
echo ""
echo "=== Results: $PASS passed, $FAIL failed ==="
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 8933130..7f457f8 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -2,6 +2,11 @@ name: Publish
on:
workflow_dispatch:
+ inputs:
+ force:
+ description: Republish versions that are already on Docker Hub
+ type: boolean
+ default: false
permissions:
contents: write
@@ -39,7 +44,7 @@ jobs:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- - name: Publish both tracks
+ - name: Publish new versions
env:
GH_TOKEN: ${{ github.token }}
- run: task publish
+ run: task publish FORCE=${{ inputs.force }}
diff --git a/Dockerfile b/Dockerfile
index eefebcb..26f13d3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -83,7 +83,7 @@ ARG MISE_VERSION=2026.10.24
ARG MISE_ZEROBREW_PLUGIN_COMMIT=998174989a12910f82c1f6e791a432731ed2647d
# 1.5. mise — dev tool manager; pre-approved tools defined in the global config
-# auto-install via zerobrew backend on first use at runtime. The release is
+# auto-install on first use at runtime. The release is
# pinned so Docker caching cannot silently retain an old moving target.
RUN curl -fsSL https://mise.run | MISE_VERSION="${MISE_VERSION}" MISE_INSTALL_PATH=/usr/local/bin/mise sh \
&& mkdir -p /opt/mise \
@@ -190,6 +190,23 @@ RUN case "${OPENCODE_VERSION}" in \
esac \
&& install -m 0755 "/usr/local/lib/opencode/${entrypoint}" /usr/local/bin/entrypoint.sh
+# Lock each "latest" tool in the system config to the release that is newest at
+# build time. First runs then download straight from the locked URL instead of
+# fetching release lists (codex's is ~10 MB, past mise's 3s timeout) or calling
+# the rate-limited GitHub API. Tools users add still resolve at runtime.
+# OPENCODE_VERSION is referenced so every opencode release re-locks rather than
+# reusing a cached layer. mise writes a temp file beside the lockfile whenever
+# it checks it, so the opencode user must own /etc/mise.
+RUN echo "locking mise tools for opencode ${OPENCODE_VERSION}" \
+ && cd / \
+ && MISE_LOCKFILE=1 MISE_FETCH_REMOTE_VERSIONS_TIMEOUT=60s \
+ MISE_CACHE_DIR=/tmp/mise-lock-cache MISE_STATE_DIR=/tmp/mise-lock-state \
+ mise lock -g --platform linux-x64,linux-arm64 \
+ && rm -rf /tmp/mise-lock-cache /tmp/mise-lock-state \
+ && chmod 0644 /etc/mise/mise.lock \
+ && chown opencode:opencode /etc/mise /etc/mise/mise.lock \
+ && chown -R opencode:opencode /opt/mise
+
# Verify runtime and set up login-shell PATH and auto-install handler
RUN opencode --version \
&& install -m 0644 /dev/null /etc/mise/empty.toml \
diff --git a/README.md b/README.md
index 948486b..6712fcf 100644
--- a/README.md
+++ b/README.md
@@ -1,186 +1,343 @@
-# Opencode Server
-
-[](https://hub.docker.com/r/sprisa/opencode) [](https://hub.docker.com/r/sprisa/opencode)
- [](https://artifacthub.io/packages/search?repo=opencode-server)
+
+
Opencode Server
+
Run opencode as a server in Docker or Kubernetes.
+
The opencode web UI and API in one Ubuntu image, with dev tools that install the first time you use them.
+
+ Quick start ·
+ Tools ·
+ Configuration ·
+ Kubernetes
+
+
+
+
+
+
+
+
+
+
+
+
+**opencode-server** is a Docker image for [opencode](https://github.com/anomalyco/opencode),
+the open source AI coding agent. It runs `opencode serve`, so you get opencode's
+web UI and API on one port. Start the container, open it in your browser, and
+work on the project you mounted.
+
+- **Sign in with a password.** The web UI and API share port 4096. You set the
+ password, or the server generates one for you.
+- **Install tools on first use.** Run `gh`, `rg`, `node`, `claude`, or any other
+ [listed tool](#tools) and it installs on the spot. Agents get the same
+ behavior, and the image stays small.
+- **Bring your Claude or ChatGPT plan.** Sign in from opencode's web UI with the
+ subscription you already have; see
+ [Use your Claude or ChatGPT subscription](#use-your-claude-or-chatgpt-subscription).
+- **Keep one folder.** Your config, sessions, and projects live in
+ `/home/opencode`. Mount a volume there and the rest of the container can be
+ thrown away.
+- **Run it on Kubernetes.** We run this image on Kubernetes for
+ [Codeplace](https://www.codeplace.app), one pod per user. See
+ [Kubernetes](#kubernetes) for the setup.
+
+The image is published to Docker Hub as
+[`sprisa/opencode`](https://hub.docker.com/r/sprisa/opencode).
+
+## Quick start
+
+Run this from the folder where you want opencode to keep its files:
+
+```sh
+docker run -it -p 4096:4096 -v $(pwd):/home/opencode sprisa/opencode:latest
+```
-[](https://github.com/sprisa/opencode-server)
+The server prints a generated password at startup, on the `server password`
+line. Open and sign in with it. To choose your own, add
+`-e OPENCODE_PASSWORD=change-me`. If the container runs in the background, get
+the password from its logs:
-[](https://railway.com/deploy/opencode-server?referralCode=KSFpZz&utm_medium=integration&utm_source=template&utm_campaign=generic)
+```sh
+docker logs 2>&1 | grep 'server password'
+```
+The current folder becomes the container's home directory. opencode saves its
+config, sessions, and dotfiles there, and starts in the `workspace/` subfolder.
+Put your projects in `workspace/`.
+To check the API from a script, use HTTP Basic auth with the username `opencode`:
-A fully featured Ubuntu Docker image for running [opencode](https://github.com/anomalyco/opencode). Minimal image size with support for agent installable tools and CLIs with `mise`.
+```sh
+curl --fail --user opencode: http://localhost:4096/api/info
+```
-Built for Docker and Kubernetes support.
+### Mount an existing project
-Published to Docker Hub as `sprisa/opencode:` where `` matches the release pinned in `version.txt` (the **v2** line — also tagged `:latest` and `:v2`). The **v1** line is still supported, pinned in `version-v1.txt`, and published with a mutable `:v1` tag.
+The command above writes opencode's config and hidden folders into the folder
+you mount. To work on an existing project without that, use two mounts. A Docker
+volume holds the home directory, and your project goes at `~/workspace`:
-## What's inside
+```sh
+docker run -it -p 4096:4096 \
+ -v opencode-home:/home/opencode \
+ -v "$(pwd)":/home/opencode/workspace \
+ sprisa/opencode:latest
+```
-| Layer | Details |
-|---|---|
-| **Base OS** | ubuntu:26.04 |
-| **User** | `opencode` (uid/gid 1000), passwordless sudo |
-| **opencode** | Pinned in `version.txt` (v2, default) / `version-v1.txt` (v1, legacy) as `OPENCODE_VERSION` build arg |
-| **Lazy Installed Tools** | Node, Python3 (see below) |
-| **Homebrew** | Linux-native Homebrew (`/home/linuxbrew/.linuxbrew`) — `brew` on PATH |
-| **zerobrew** | Faster Homebrew alternative (`zb` on PATH) -- used as mise backend for lazy-installed tools |
-| **mise** | Dev tool manager — tools listed below install on first use via `zerobrew` backend |
-| **CLI utilities** | git, curl, less, unzip |
-| **Init** | tini as PID 1 (zombie reaping, clean shutdown) |
+Docker creates the `opencode-home` volume on the first run. It keeps your config
+and sessions between containers, and your project folder only holds your code.
-### Lazy-installed tools
+## Tools
-These tools install on first use (via mise → github/zerobrew):
+The image comes with git, curl, ssh, less, and unzip. The tools below install
+through [mise](https://mise.jdx.dev) the first time someone runs the command:
| Tool | Command | Backend |
|---|---|---|
-| GitHub CLI | `gh` | github |
-| jq | `jq` | github |
-| GitLab CLI | `glab` | core |
-| Ruby | `ruby` | zerobrew |
-| ripgrep | `rg` | github |
-| fd | `fd` | github |
+| GitHub CLI | `gh` | mise core |
+| jq | `jq` | mise core |
+| GitLab CLI | `glab` | mise core |
+| Ruby | `ruby` | mise core |
+| ripgrep | `rg` | mise core |
+| fd | `fd` | mise core |
| Wget | `wget` | zerobrew |
-| Vim | `vim` | core |
-| Micro | `micro` | github |
+| Vim | `vim` | mise core |
+| Micro | `micro` | mise core |
| Nano | `nano` | zerobrew |
-| Python 3 | `python3` | core |
-| Node.js | `node` | core |
+| Python 3 | `python3` | mise core |
+| Node.js | `node` | mise core |
| Sapling | `sl` | github |
+| clonetree | `clonetree` | github |
+| Codex | `codex` | mise core |
+| Claude Code | `claude` | mise core |
+| cloudflared | `cloudflared` | mise core |
-The image ships with a system config at `/etc/mise/config.toml` with these pre-approved tools. Users can add or override tools by creating `~/.config/mise/config.toml` — mise merges both.
+Most tools install in a few seconds. They're saved to `/opt/mise`, outside the
+home directory, so a new container downloads them again the first time they're
+used.
-## Usage
+Each image locks these tools to the newest release at build time, in
+`/etc/mise/mise.lock`. First runs download that release directly, with no
+version lookup and no GitHub API calls, and a newer image brings newer
+versions. To get the newest release of one of these tools in an older image,
+run `mise upgrade ` or `mise use @latest`. A bare `mise use `
+keeps the image's version. Tools that aren't in the table always resolve to
+their newest release.
-### Quick start
+
+What the backends mean
-```bash
-docker run -it -p 4096:4096 -v $(pwd):/home/opencode sprisa/opencode:latest
-```
+**mise core** tools use a name from mise's built-in registry, for example
+`ripgrep` rather than `github:BurntSushi/ripgrep`. They're preferred. **github**
+tools look up releases through the GitHub API, which is rate limited. **zerobrew**
+tools install from Homebrew packages and add a per-tool install prefix. Those two
+are only used for tools that aren't in the mise registry.
-The server starts on port 4096. Mount your project at `/home/opencode` to persist the entire home directory (dotfiles, config, and `~/workspace`).
+Ruby uses mise's prebuilt versions (`ruby.compile = false`) because the image has
+no compiler. Gems that ship prebuilt, such as nokogiri, install normally. Gems
+that build native code need `sudo apt-get install build-essential` first.
-### Environment variables
+
-| Variable | Default | Description |
-|---|---|---|
-| `OPENCODE_PORT` | `4096` | Port the server listens on |
-| `OPENCODE_PASSWORD` | *(generated by v2)* | v2 server password; takes precedence over `OPENCODE_SERVER_PASSWORD` |
-| `OPENCODE_SERVER_PASSWORD` | *(none)* | v1 server password; also accepted by v2 as a compatibility alias |
-| `OPENCODE_SERVER_USERNAME` | `opencode` | v1 only: override the HTTP Basic auth username. V2 always uses `opencode` |
-| `OPENCODE_CORS_ORIGIN` | *(none)* | Additional allowed browser origin, passed as `--cors` |
-| `OPENCODE_PRINT_LOGS` | `false` | Set to `true` to print OpenCode logs to container stderr |
-| `OPENCODE_LOG_LEVEL` | *(OpenCode default)* | `DEBUG`, `INFO`, `WARN`, or `ERROR`; v2 also accepts lowercase and its extended levels (`trace`, `fatal`, etc.) |
-| `OPENCODE_INSTALL_HOME_TOOLS` | `false` | After a 3-second delay, install tools from `~/.config/mise/config.toml` in the background |
-
-The Dockerfile selects `entrypoint.sh` for v2 and `entrypoint-v1.sh` for v1 based
-on `OPENCODE_VERSION`. Both run foreground `opencode serve` on `0.0.0.0` and share
-the same home/tool initialization. The v2 entrypoint normalizes log levels to the
-lowercase values required by its CLI.
-
-### Authentication and health checks
-
-V2 always requires a password for API requests. Set `OPENCODE_PASSWORD` (or the
-legacy `OPENCODE_SERVER_PASSWORD`) for a stable password; otherwise v2 generates
-one and prints it at startup. The web sign-in page is publicly accessible, while
-the API uses HTTP Basic auth with username `opencode` or a paired browser session.
-V1 enables HTTP Basic auth when `OPENCODE_SERVER_PASSWORD` is set.
-
-V2's authenticated health/info endpoint is `/api/info`; v1 uses `/global/health`.
-The old v1 API paths on v2 can return the HTML web app, so a 200 from one of those
-paths is not an API health or authentication check.
-
-```bash
-curl --fail --user opencode:secret http://localhost:4096/api/info
+### Use your Claude or ChatGPT subscription
+
+You can sign in with a Claude or ChatGPT subscription you already have. Both
+sign-ins happen in opencode's web UI.
+
+**Claude:** open the terminal built into opencode's web UI and run:
+
+```sh
+claude auth login
```
-### Upgrading from v1
+It prints a sign-in link. Open the link in your browser, then paste the code it
+shows back into the terminal. Then connect the Claude agent from the opencode UI.
-`:latest` now follows v2. Use `:v1` to keep an existing deployment on the v1 line,
-or `:v2` to follow v2 explicitly. V2 reads supported v1 configuration from the
-same locations and migrates legacy session data, but has a new server API/client
-contract and plugin API. Existing v1 API integrations and plugins need migration;
-see the [upstream migration guide](https://opencode.ai/v2/docs/migrate-v1).
+**ChatGPT:** sign in through opencode with the device code option. You don't
+need the Codex CLI. Turn device codes on in ChatGPT first: under **App
+security** in ChatGPT's security settings, enable **Enable device code sign-in
+for Codex, Excel, PowerPoint, and Word**.
-### Examples
+Both sign-ins are saved in the home directory, so they last as long as you keep
+your home mount.
-**With authentication:**
-```bash
-docker run -it -p 4096:4096 \
- -e OPENCODE_PASSWORD=secret \
- -v myproject:/home/opencode \
- sprisa/opencode:latest
+### Add your own tools
+
+Tools you add go in `~/.config/mise/config.toml`, which lives on the home volume.
+mise merges it with the image's defaults in `/etc/mise/config.toml`:
+
+```sh
+mise use -g go@latest
```
-**With CORS enabled for a specific origin:**
-```bash
-docker run -it -p 4096:4096 \
- -e OPENCODE_CORS_ORIGIN=https://myapp.example.com \
- sprisa/opencode:latest
+Tools you add this way also install on first use. To install them in the
+background each time the container starts, set `OPENCODE_INSTALL_HOME_TOOLS=true`.
+
+Need a system package instead? The `opencode` user has passwordless sudo:
+
+```sh
+sudo apt-get update && sudo apt-get install -y
```
-**Custom port:**
-```bash
+opencode loads an instruction file, `/etc/opencode/mise-instructions.md`, that
+tells agents to try mise before apt.
+
+
+Other package managers and paths
+
+- **Homebrew** (`brew`) is installed under `/home/linuxbrew/.linuxbrew`. It runs on
+ its own bundled Ruby.
+- **zerobrew** (`zb`), a faster Homebrew client, is at `/usr/local/bin/zb`.
+- **`~/.local/bin`** is on `PATH` and writable, so you can drop your own binaries
+ there.
+- The image runs on Ubuntu 26.04 with [tini](https://github.com/krallin/tini) as
+ PID 1, so the server shuts down cleanly and leftover processes get cleaned up.
+
+
+
+## Configuration
+
+Configure the server with environment variables:
+
+| Variable | Default | What it does |
+|---|---|---|
+| `OPENCODE_PASSWORD` | generated | Password for the web UI and API. A generated password changes on every restart. |
+| `OPENCODE_PORT` | `4096` | Port the server listens on. |
+| `OPENCODE_CORS_ORIGIN` | none | An extra browser origin allowed to call the API, such as `https://myapp.example.com`. |
+| `OPENCODE_PRINT_LOGS` | `false` | Set to `true` to print opencode's logs to the container output. |
+| `OPENCODE_LOG_LEVEL` | opencode's default | `DEBUG`, `INFO`, `WARN`, or `ERROR`. v2 also accepts lowercase. |
+| `OPENCODE_INSTALL_HOME_TOOLS` | `false` | Set to `true` to install the tools in `~/.config/mise/config.toml` in the background, 3 seconds after startup. |
+| `OPENCODE_SERVER_PASSWORD` | none | The password variable for v1 images. v2 accepts it as an older name, and `OPENCODE_PASSWORD` wins if both are set. |
+| `OPENCODE_SERVER_USERNAME` | `opencode` | v1 images only: changes the API username. |
+
+The defaults are for v2, which `latest` runs. On v1 images, the server has no
+password unless you set `OPENCODE_SERVER_PASSWORD`.
+
+For example, to run on port 8080 with logs:
+
+```sh
docker run -it -p 8080:8080 \
-e OPENCODE_PORT=8080 \
+ -e OPENCODE_PASSWORD=change-me \
+ -e OPENCODE_PRINT_LOGS=true \
sprisa/opencode:latest
```
-## Building & pushing
+## Deploy
+
+### Kubernetes
+
+We run this image in production on Kubernetes for
+[Codeplace](https://www.codeplace.app). Each user gets their own opencode pod
+with its own persistent volume. Codeplace uses the published `sprisa/opencode`
+image unchanged and adds its own setup from an init container. You can customize
+it the same way, without forking the image.
+
+For your own Deployment or StatefulSet, set up these four things:
+
+- **Storage.** Mount a PersistentVolumeClaim at `/home/opencode`. Nothing outside
+ it is kept when the pod restarts.
+- **User.** The server runs as uid and gid 1000. Set `fsGroup: 1000` so it can
+ write to the volume.
+- **Password.** Pass `OPENCODE_PASSWORD` from a Secret. Otherwise the password
+ changes on every restart.
+- **Probes.** Use a TCP probe on port 4096. `/api/info` returns 401 without
+ credentials, so it isn't a good plain HTTP probe.
+
+### Railway
+
+[](https://railway.com/deploy/opencode-server?referralCode=KSFpZz&utm_medium=integration&utm_source=template&utm_campaign=generic)
-All docker commands go through `task` which reads the pinned version from `version.txt`:
+## Versions and tags
-```bash
-task docker:build # Build locally as sprisa/opencode: (v2)
-task docker:login # Docker Hub login (needs $DOCKER_USER / $DOCKER_PASS)
-task docker:push # Push v2 as +latest, +v2, + (amd64/arm64)
-task publish # Push both tracks and create missing GitHub Releases
-task docker:build:v1 # Build the v1 image locally
-task docker:push:v1 # Push v1 as + and +v1
+| Tag | Follows |
+|---|---|
+| `latest`, `v2` | The newest opencode v2 release |
+| `2.x.y` | One exact opencode release |
+| `v1` | The newest opencode v1 release, for existing v1 setups |
+
+Each image tag matches the opencode version inside it. The repo pins those
+versions in `version.txt` (v2) and `version-v1.txt` (v1).
+
+
+Upgrading from v1
+
+`latest` moved from v1 to v2. To stay on v1, switch to the `v1` tag.
+
+v2 reads your v1 config from the same locations and migrates your old sessions.
+Its server API and plugin API are new, though, so v1 API integrations and plugins
+need changes. See opencode's
+[migration guide](https://opencode.ai/v2/docs/migrate-v1).
+
+A few behaviors differ between the two lines:
+
+- **Auth.** v2 always requires a password. v1 only turns on auth when
+ `OPENCODE_SERVER_PASSWORD` is set.
+- **Health check.** v2 uses `/api/info`. v1 uses `/global/health`. On v2, the
+ old v1 paths can return the web app's HTML with a 200, so they don't prove the
+ API is up.
+
+
+
+## Development
+
+Build and publish tasks run through [Task](https://taskfile.dev) and read the
+pinned versions from `version.txt` and `version-v1.txt`:
+
+```sh
+task docker:build # Build v2 locally as sprisa/opencode:
+task docker:build:v1 # Build v1 locally
+task update # Bump both pins to the newest stable opencode releases
+task publish # Push versions not yet on Docker Hub and create missing GitHub releases
```
-`task publish` refreshes the versioned images and mutable tags for both tracks,
-retains existing GitHub releases, and creates missing releases tagged at the
-checked-out commit. Only v2 releases are marked GitHub's **Latest** release.
+The end-to-end tests run against a built image:
+
+```sh
+bash tests/test-server-e2e.sh sprisa/opencode:
+bash tests/test-toolchain-e2e.sh sprisa/opencode:
+bash tests/test-home-tools-e2e.sh sprisa/opencode:
+bash tests/test-mise-lock-e2e.sh sprisa/opencode:
+```
-### Manual GitHub Actions publishing
+The image locks its mise tools during the build, so building needs network
+access. A new opencode version always produces a fresh lock. To refresh tool
+versions without changing the opencode version, build with `--no-cache`.
-Run **Actions → Publish → Run workflow** to publish both pinned versions from
-`main`. Add these repository Actions secrets first:
+
+Releases and publishing
-- `DOCKERHUB_USERNAME`: Docker Hub account with push access to `sprisa/opencode`.
-- `DOCKERHUB_TOKEN`: Docker Hub access token with Read & Write permissions.
+`task update` uses an authenticated GitHub CLI (`gh`) and `jq` to find the
+newest stable v2 and v1 [opencode releases](https://github.com/anomalyco/opencode/releases).
+It skips drafts, prereleases, and component releases, and never moves a pin
+backwards. A scheduled workflow, `opencode release checker`, runs the same check
+and opens a pull request for each line that has a new release.
-The workflow checks out `main` with full tag history, sets up multi-architecture
-builds, logs in to Docker Hub, and runs `task publish`. GitHub releases use the
-automatically provided `GITHUB_TOKEN` with `contents: write` permission.
+`task publish` builds and pushes multi-arch (amd64 and arm64) images for each
+line whose pinned version isn't on Docker Hub yet, and moves that line's tags.
+A line whose version is already published is skipped, so its tags stay where
+they are. It also creates any missing GitHub releases at the current commit.
+Only v2 releases are marked as GitHub's latest release.
-## Updating the opencode version
+To ship image changes without a new opencode version, republish with
+`task publish FORCE=true`. Other tasks:
-```bash
-task update
+```sh
+task docker:login # Log in to Docker Hub (needs $DOCKER_USER and $DOCKER_PASS)
+task docker:push # Push v2 as , latest, and v2
+task docker:push:v1 # Push v1 as and v1
```
-Uses the authenticated GitHub CLI (`gh`) and `jq` to fetch all upstream release
-pages and select the highest stable [v2 and v1 releases](https://github.com/anomalyco/opencode).
-Updates `version.txt` (v2) and `version-v1.txt` (v1) without downgrading either
-pin. Drafts, prereleases, and component releases are excluded. The scheduled
-`opencode release checker` workflow uses the same discovery script and opens a
-bump PR per track.
+To publish from GitHub instead, run **Actions → Publish → Run workflow** on
+`main`. Tick **force** to republish versions that are already on Docker Hub.
+Add two repository secrets first:
-## Runtime notes
+- `DOCKERHUB_USERNAME`: a Docker Hub account that can push to `sprisa/opencode`.
+- `DOCKERHUB_TOKEN`: a Docker Hub access token with read and write access.
-- The `opencode` user has passwordless sudo, so you can `su - opencode -c 'apt install '` inside the container.
-- The root filesystem is ephemeral; mount `/home/opencode` as the persistent volume for all user data (dotfiles, config, projects). The `~/workspace` subdirectory is the default workdir.
-- `~/.local/bin` is on PATH and user-writable, useful for dropping custom tools at runtime.
-- Node version can be switched at runtime with `n ` (e.g. `n lts`).
-- Homebrew is installed under `/home/linuxbrew/.linuxbrew` (outside the persistent volume). It uses its bundled portable Ruby — no system Ruby needed.
-- Zerobrew (`zb`) is installed at `/usr/local/bin/zb` with its prefix at `~/.local/share/zerobrew/prefix` on PATH for accessing formula binaries.
-- **Lazy-installed tools** (see table above): run any listed tool and mise auto-installs it via zerobrew or github backend on first use. The image ships defaults in `/etc/mise/config.toml`; create `~/.config/mise/config.toml` to add your own — mise merges both.
-- OpenCode includes a managed instruction at `/etc/opencode/mise-instructions.md` reminding agents to prefer mise over apt for development tools.
+The workflow creates GitHub releases with the built-in `GITHUB_TOKEN`.
+
---
-Use in production at www.codeplace.app
+Runs in production on Kubernetes at [codeplace.app](https://www.codeplace.app).
+Licensed under [MPL 2.0](LICENSE).
diff --git a/Taskfile.yml b/Taskfile.yml
index 85fd5f0..a8a1100 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -80,7 +80,7 @@ tasks:
- "echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdin"
publish:
- desc: "Push both pinned tracks (v2 + v1) and create missing GitHub Releases"
+ desc: "Push pinned tracks (v2 + v1) not yet on Docker Hub and create missing GitHub Releases (FORCE=true republishes)"
preconditions:
- sh: command -v gh >/dev/null
msg: "GitHub CLI not found. Install it: brew install gh"
@@ -90,10 +90,19 @@ tasks:
- task: publish:v2
- task: publish:v1
+ # A version tag that already exists on Docker Hub is skipped, so publishing
+ # one track doesn't rebuild the other or move its :v1/:v2/:latest tags.
+ # FORCE=true republishes anyway, e.g. to ship image changes without a new
+ # opencode version.
publish:v2:
- desc: "Push the v2 image (:latest + :v2 + ) and create the v2 GitHub Release if missing"
+ desc: "Push the v2 image (:latest + :v2 + ) unless is on Docker Hub, and create the v2 GitHub Release if missing"
cmds:
- - task: docker:push
+ - |
+ if [ "{{.FORCE}}" != "true" ] && docker buildx imagetools inspect {{.OCI}}:{{.VERSION}} >/dev/null 2>&1; then
+ echo "{{.OCI}}:{{.VERSION}} is already on Docker Hub, skipping push (FORCE=true republishes)"
+ else
+ task docker:push
+ fi
- |
if gh release view v{{.VERSION}} --repo {{.RELEASE_REPO}} >/dev/null 2>&1; then
echo "GitHub Release v{{.VERSION}} already exists, skipping"
@@ -103,9 +112,14 @@ tasks:
fi
publish:v1:
- desc: "Push the v1 image (:latest stays on v2) with and :v1 tags, create the v1 GitHub Release if missing"
+ desc: "Push the v1 image (:latest stays on v2) with and :v1 tags unless is on Docker Hub, and create the v1 GitHub Release if missing"
cmds:
- - task: docker:push:v1
+ - |
+ if [ "{{.FORCE}}" != "true" ] && docker buildx imagetools inspect {{.OCI}}:{{.VERSION_V1}} >/dev/null 2>&1; then
+ echo "{{.OCI}}:{{.VERSION_V1}} is already on Docker Hub, skipping push (FORCE=true republishes)"
+ else
+ task docker:push:v1
+ fi
- |
if gh release view v{{.VERSION_V1}} --repo {{.RELEASE_REPO}} >/dev/null 2>&1; then
echo "GitHub Release v{{.VERSION_V1}} already exists, skipping"
diff --git a/mise-config.toml b/mise-config.toml
index 0667b21..dc00dc4 100644
--- a/mise-config.toml
+++ b/mise-config.toml
@@ -1,15 +1,22 @@
+[settings]
+ruby.compile = false # runtime image has no compiler toolchain
+
[tools]
-"github:cli/cli" = "latest" # shim:gh
-"github:jqlang/jq" = "latest"
+"github-cli" = "latest" # shim:gh
+"jq" = "latest"
"glab" = "latest"
-"zerobrew:ruby" = "latest"
-"github:BurntSushi/ripgrep" = "latest" # shim:rg
-"github:sharkdp/fd" = "latest"
+"ruby" = "latest" # shim:ruby,gem,bundle
+"ripgrep" = "latest" # shim:rg
+"fd" = "latest"
"zerobrew:wget" = "latest"
"vim" = "latest"
-"github:zyedidia/micro" = "latest"
+"micro" = "latest"
"zerobrew:nano" = "latest"
"python" = "latest" # shim:python,python3
"node" = "latest"
"npm" = "latest" # shim:npm,npx
"github:facebook/sapling" = "latest" # shim:sl
+"github:sprisa/clonetree" = "latest"
+"codex" = "latest"
+"claude" = "latest"
+"cloudflared" = "latest"
diff --git a/mise-instructions.md b/mise-instructions.md
index f89c966..c4936fa 100644
--- a/mise-instructions.md
+++ b/mise-instructions.md
@@ -7,5 +7,7 @@ Prefer `mise` over `apt` for missing development tools and runtimes.
- `mise install `: install a configured tool.
- `mise exec -- `: one-off use.
-Use `@` only when pinning is required. Use `apt` only for system
+Use `@` only when pinning is required. Image tools are locked to the
+image's build; for a newer release of one, use `mise use @latest` or
+`mise upgrade `. Use `apt` only for system
packages mise cannot manage (you must check first). Image tools install lazily; do not bulk-install.
diff --git a/test-toolchain-e2e.sh b/test-toolchain-e2e.sh
deleted file mode 100644
index f98e7d2..0000000
--- a/test-toolchain-e2e.sh
+++ /dev/null
@@ -1,36 +0,0 @@
-#!/usr/bin/env bash
-# Exercise the pinned package managers and their real install paths.
-# Usage: bash test-toolchain-e2e.sh
-set -euo pipefail
-
-IMAGE="${1:?usage: test-toolchain-e2e.sh }"
-NAME="opencode-toolchain-e2e-$$"
-cleanup() { docker rm -f "$NAME" >/dev/null 2>&1 || true; }
-trap cleanup EXIT
-
-echo "Testing package managers and lazy installs (${IMAGE}; 5-minute timeout)..."
-docker run --rm -i --name "$NAME" -e GITHUB_TOKEN --entrypoint timeout "$IMAGE" 300 bash -s <<'TEST'
-set -euo pipefail
-
-brew --version
-mise --version
-zb --version
-git -C /opt/mise/plugins/zerobrew rev-parse HEAD
-
-# These commands must start lazy and then install via the zerobrew plugin,
-# including its per-tool root initialization and runtime library paths.
-for command in ruby wget nano; do
- [ "$(command -v "$command")" = "/opt/auto-install-shims/$command" ]
-done
-ruby --version
-wget --version
-nano --version
-
-# Also exercise Homebrew itself and the standalone zbx wrapper, rather than
-# only checking that the pinned package-manager executables start.
-brew install hello
-hello --version
-zbx hello --version
-TEST
-
-echo "PASS: Homebrew, mise, zerobrew plugin lazy installs, and zbx ($IMAGE)"
diff --git a/test-bump-version.sh b/tests/test-bump-version.sh
similarity index 98%
rename from test-bump-version.sh
rename to tests/test-bump-version.sh
index ff335b9..9c2ba7d 100644
--- a/test-bump-version.sh
+++ b/tests/test-bump-version.sh
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# Quick manual test for bump-version.sh logic
-# Run: bash test-bump-version.sh
+# Run: bash tests/test-bump-version.sh
set -euo pipefail
# Temporary fixture commits must also work on CI runners with no Git identity.
@@ -9,7 +9,7 @@ export GIT_AUTHOR_EMAIL="test@example.com"
export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
-SCRIPT="$(cd "$(dirname "$0")" && pwd)/scripts/bump-version.sh"
+SCRIPT="$(cd "$(dirname "$0")/.." && pwd)/scripts/bump-version.sh"
log() { echo " $*"; }
pass() { log "PASS"; }
diff --git a/test-home-tools-e2e.sh b/tests/test-home-tools-e2e.sh
similarity index 96%
rename from test-home-tools-e2e.sh
rename to tests/test-home-tools-e2e.sh
index 3d94507..176e067 100644
--- a/test-home-tools-e2e.sh
+++ b/tests/test-home-tools-e2e.sh
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# End-to-end test for the delayed home-tool installer.
-# Usage: test-home-tools-e2e.sh [image]
+# Usage: bash tests/test-home-tools-e2e.sh [image]
set -euo pipefail
IMAGE="${1:-opencode-test:latest}"
@@ -121,7 +121,7 @@ if [ "${installed}" -ne 1 ]; then
fi
# The system config and project config must remain lazy.
-if docker exec "${NAME}" bash -c 'for path in /opt/mise/installs/github-jqlang-jq/*/jq /opt/mise/installs/node/*/bin/node; do [ -x "$path" ] && exit 0; done; exit 1'; then
+if docker exec "${NAME}" bash -c 'for path in /opt/mise/installs/jq/*/jq /opt/mise/installs/node/*/bin/node; do [ -x "$path" ] && exit 0; done; exit 1'; then
echo "system/project tool was eagerly installed" >&2
exit 1
fi
diff --git a/tests/test-mise-lock-e2e.sh b/tests/test-mise-lock-e2e.sh
new file mode 100644
index 0000000..4e5e1d8
--- /dev/null
+++ b/tests/test-mise-lock-e2e.sh
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Exercise the build-time mise lockfile in the real image.
+# Usage: bash tests/test-mise-lock-e2e.sh
+#
+# Runs without GITHUB_TOKEN on purpose: locked tools must not need the GitHub
+# API, and codex's release list (~10 MB) must never be fetched on first use.
+set -euo pipefail
+
+IMAGE="${1:?usage: tests/test-mise-lock-e2e.sh }"
+
+echo "Checking the image lockfile and locked first runs (${IMAGE})..."
+docker run --rm -i --entrypoint timeout "$IMAGE" 600 bash -s <<'TEST'
+set -euo pipefail
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+lock=/etc/mise/mise.lock
+[ -f "$lock" ] || fail "missing $lock"
+[ "$(stat -c %U "$lock")" = opencode ] || fail "$lock must be owned by opencode"
+[ -w /etc/mise ] || fail "/etc/mise must be writable by opencode"
+
+# locked_version prints the version locked for that tool.
+locked_version() {
+ awk -v a="[[tools.$1]]" -v b="[[tools.\"$1\"]]" '
+ $0 == a || $0 == b { found = 1; next }
+ found && /^version = / { gsub(/"/, "", $3); print $3; exit }
+ ' "$lock"
+}
+
+# install_dir matches mise's install directory naming.
+install_dir() { printf '/opt/mise/installs/%s' "$(printf '%s' "$1" | tr ':/' '--')"; }
+
+# Every non-zerobrew tool in the system config is locked to a real version.
+grep -E '^\s*"' /etc/mise/config.toml | cut -d'"' -f2 | while read -r key; do
+ case "$key" in zerobrew:*) continue ;; esac
+ version="$(locked_version "$key")"
+ case "$version" in
+ "" | latest) fail "$key is not locked to a concrete version (got '${version}')" ;;
+ esac
+done
+echo "ok: every mise core and github tool is locked"
+
+# First runs install the locked version without fetching any release list.
+# codex is the regression case: its list is too large for mise's timeout.
+cp "$lock" /tmp/lock.before
+for pair in jq:jq codex:codex github-cli:gh github:sprisa/clonetree:clonetree; do
+ key="${pair%:*}" command="${pair##*:}"
+ log="/tmp/first-run-${command}.log"
+ if ! MISE_DEBUG=1 timeout 60 "$command" --version "$log" 2>&1; then
+ tail -5 "$log" >&2
+ fail "$command did not finish its first run within 60s"
+ fi
+ if grep -qE 'api\.github\.com|mise-versions\.jdx\.dev/api|Remote versions cannot be fetched|Failed to resolve tool version list' "$log"; then
+ grep -E 'api\.github\.com|mise-versions\.jdx\.dev/api|Remote versions|Failed to resolve' "$log" | head -3 | cut -c1-200 >&2
+ fail "$command looked up remote versions instead of using the lockfile"
+ fi
+ version="$(locked_version "$key")"
+ [ -d "$(install_dir "$key")/$version" ] || fail "$command did not install locked version $version"
+ echo "ok: $command installed locked $version with no version lookup"
+done
+cmp -s /tmp/lock.before "$lock" || fail "the lockfile changed during first runs"
+
+# Tools the image doesn't ship resolve latest at runtime and leave no lockfiles.
+mkdir -p ~/workspace/lock-project && cd ~/workspace/lock-project
+mise use shellcheck >/tmp/use.log 2>&1 || { tail -3 /tmp/use.log >&2; fail "mise use shellcheck failed"; }
+newest="$(mise latest shellcheck)"
+installed="$(shellcheck --version | sed -n 's/^version: //p')"
+[ "$installed" = "$newest" ] || fail "shellcheck resolved $installed, newest is $newest"
+[ ! -e mise.lock ] || fail "mise use wrote mise.lock into the project"
+[ ! -e ~/.config/mise/mise.lock ] || fail "mise wrote a user lockfile"
+echo "ok: bare 'mise use shellcheck' resolves latest ($installed) without writing lockfiles"
+TEST
+
+# An old image keeps its locked versions with no lookup, and explicit requests
+# still reach the newest release. Simulate a build that locked jq 1.7.1 and
+# fd 10.1.0 for their "latest" requests.
+echo "Checking old-image lockfile behavior (${IMAGE})..."
+docker run --rm -i -u root --entrypoint timeout "$IMAGE" 900 bash -s <<'TEST'
+set -euo pipefail
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+cp /etc/mise/config.toml /tmp/config.toml
+sed -i -e 's/^"jq" = "latest"/"jq" = "1.7.1"/' -e 's/^"fd" = "latest"/"fd" = "10.1.0"/' /etc/mise/config.toml
+(cd / && MISE_LOCKFILE=1 MISE_CACHE_DIR=/tmp/root-cache MISE_STATE_DIR=/tmp/root-state \
+ mise lock -g --platform linux-x64,linux-arm64 jq fd >/dev/null)
+cp /tmp/config.toml /etc/mise/config.toml
+for tool in jq fd; do
+ sed -i "/^\[\[tools.$tool\]\]/,/^\[\[/ s/^specifiers = .*/specifiers = [\"latest\"]/" /etc/mise/mise.lock
+done
+chown opencode:opencode /etc/mise/mise.lock
+chown -R opencode:opencode /opt/mise
+
+sudo -u opencode HOME=/home/opencode PATH="$PATH" MISE_DATA_DIR=/opt/mise bash -s <<'USER'
+set -euo pipefail
+fail() { echo "FAIL: $*" >&2; exit 1; }
+cd ~/workspace
+
+MISE_DEBUG=1 jq --version >/tmp/old.log 2>&1 || { tail -3 /tmp/old.log >&2; fail "jq failed"; }
+grep -q '^jq-1.7.1$' /tmp/old.log || fail "old lockfile's jq 1.7.1 was not used"
+if grep -qE 'api\.github\.com|mise-versions\.jdx\.dev/api' /tmp/old.log; then
+ fail "old lockfile still looked up remote versions"
+fi
+echo "ok: an old lockfile keeps its version with no lookup"
+
+newest="$(mise latest jq)"
+[ "$newest" != 1.7.1 ] || fail "test needs a jq release newer than 1.7.1"
+check() { # check
+ local expected="$1" description="$2"
+ shift 2
+ rm -rf ~/workspace/lock-project && mkdir -p ~/workspace/lock-project && cd ~/workspace/lock-project
+ "$@" >/tmp/check.log 2>&1 || { tail -3 /tmp/check.log >&2; fail "$description failed"; }
+ [ "$(jq --version)" = "jq-$expected" ] || fail "$description gave $(jq --version), expected jq-$expected"
+ echo "ok: $description gives jq $expected"
+}
+check 1.7.1 "bare 'mise use jq'" mise use jq
+check "$newest" "'mise use jq@latest'" mise use jq@latest
+check "$newest" "'mise upgrade jq'" bash -c 'mise use jq && mise upgrade jq'
+
+# Bare `mise upgrade` outside a project bumps image tools and rewrites the
+# image lockfile. fd is only touched here, so earlier checks can't mask it.
+# Like it does without a lockfile, this also installs every configured tool.
+cd ~/workspace
+[ "$(fd --version)" = "fd 10.1.0" ] || fail "old lockfile's fd 10.1.0 was not used"
+newest_fd="$(mise latest fd)"
+[ "$newest_fd" != 10.1.0 ] || fail "test needs an fd release newer than 10.1.0"
+timeout 600 mise upgrade >/tmp/upgrade.log 2>&1 || { tail -3 /tmp/upgrade.log >&2; fail "bare 'mise upgrade' failed"; }
+[ "$(fd --version)" = "fd $newest_fd" ] || fail "bare 'mise upgrade' left $(fd --version), expected fd $newest_fd"
+grep -A1 '^\[\[tools.fd\]\]' /etc/mise/mise.lock | grep -q "^version = \"$newest_fd\"" \
+ || fail "bare 'mise upgrade' did not update fd in the image lockfile"
+echo "ok: bare 'mise upgrade' upgrades fd 10.1.0 to $newest_fd and updates the lockfile"
+USER
+TEST
+
+echo "PASS: mise lockfile e2e (${IMAGE})"
diff --git a/test-release-automation.py b/tests/test-release-automation.py
similarity index 78%
rename from test-release-automation.py
rename to tests/test-release-automation.py
index 60eff36..d11d821 100644
--- a/test-release-automation.py
+++ b/tests/test-release-automation.py
@@ -9,7 +9,7 @@
import unittest
-ROOT = Path(__file__).resolve().parent
+ROOT = Path(__file__).resolve().parent.parent
class ReleaseAutomationTests(unittest.TestCase):
@@ -34,6 +34,7 @@ def setUp(self):
"DOCKER_CALLS": str(self.cwd / "docker-calls.jsonl"),
"RELEASE_FIXTURE": str(self.cwd / "releases.json"),
"RELEASE_EXISTS": "0",
+ "IMAGES_EXIST": "",
"API_FAIL": "0",
}
self.mock("gh", '''
@@ -56,8 +57,11 @@ def setUp(self):
''')
self.mock("docker", '''
import json, os, sys
+args = sys.argv[1:]
with open(os.environ["DOCKER_CALLS"], "a") as out:
- out.write(json.dumps(sys.argv[1:]) + "\\n")
+ out.write(json.dumps(args) + "\\n")
+if args[:3] == ["buildx", "imagetools", "inspect"]:
+ sys.exit(0 if args[3] in os.environ["IMAGES_EXIST"].split(",") else 1)
''')
self.run_command("git", "init", "-q")
self.run_command("git", "add", "version.txt", "version-v1.txt")
@@ -95,6 +99,13 @@ def calls(self, name):
path = self.cwd / f"{name}-calls.jsonl"
return [json.loads(line) for line in path.read_text().splitlines()] if path.exists() else []
+ def builds(self):
+ return [args for args in self.calls("docker") if args[:2] == ["buildx", "build"]]
+
+ @staticmethod
+ def tags(args):
+ return [args[i + 1] for i, arg in enumerate(args) if arg == "-t"]
+
def test_discovery_paginates_and_selects_highest_stable_version(self):
result = self.run_command("bash", "scripts/latest-releases.sh")
self.assertEqual(json.loads(result.stdout), {"v1": "1.19.10", "v2": "2.10.0"})
@@ -124,11 +135,10 @@ def test_api_failure_does_not_silently_change_pins(self):
def test_publish_pushes_both_tracks_and_sets_release_target_and_latest(self):
self.run_command("task", "publish")
- docker = self.calls("docker")
- self.assertEqual(len(docker), 2)
- tags = lambda args: [args[i + 1] for i, arg in enumerate(args) if arg == "-t"]
- self.assertEqual(tags(docker[0]), ["docker.io/sprisa/opencode:2.2.4", "docker.io/sprisa/opencode:latest", "docker.io/sprisa/opencode:v2"])
- self.assertEqual(tags(docker[1]), ["docker.io/sprisa/opencode:1.19.5", "docker.io/sprisa/opencode:v1"])
+ builds = self.builds()
+ self.assertEqual(len(builds), 2)
+ self.assertEqual(self.tags(builds[0]), ["docker.io/sprisa/opencode:2.2.4", "docker.io/sprisa/opencode:latest", "docker.io/sprisa/opencode:v2"])
+ self.assertEqual(self.tags(builds[1]), ["docker.io/sprisa/opencode:1.19.5", "docker.io/sprisa/opencode:v1"])
releases = [args for args in self.calls("gh") if args[:2] == ["release", "create"]]
self.assertEqual(len(releases), 2)
self.assertIn("--latest", releases[0])
@@ -137,10 +147,25 @@ def test_publish_pushes_both_tracks_and_sets_release_target_and_latest(self):
self.assertEqual(args[args.index("--target") + 1], self.sha)
self.assertEqual(args[args.index("--repo") + 1], "sprisa/opencode-server")
- def test_existing_releases_are_retained_while_image_aliases_are_refreshed(self):
+ def test_publish_skips_a_track_whose_version_is_already_published(self):
+ self.env["IMAGES_EXIST"] = "docker.io/sprisa/opencode:1.19.5"
+ self.run_command("task", "publish")
+ builds = self.builds()
+ self.assertEqual(len(builds), 1)
+ self.assertEqual(self.tags(builds[0]), ["docker.io/sprisa/opencode:2.2.4", "docker.io/sprisa/opencode:latest", "docker.io/sprisa/opencode:v2"])
+
+ def test_existing_releases_and_images_are_left_alone(self):
self.env["RELEASE_EXISTS"] = "1"
+ self.env["IMAGES_EXIST"] = "docker.io/sprisa/opencode:2.2.4,docker.io/sprisa/opencode:1.19.5"
self.run_command("task", "publish")
- self.assertEqual(len(self.calls("docker")), 2)
+ self.assertEqual(self.builds(), [])
+ self.assertFalse(any(args[:2] == ["release", "create"] for args in self.calls("gh")))
+
+ def test_force_republishes_existing_images(self):
+ self.env["RELEASE_EXISTS"] = "1"
+ self.env["IMAGES_EXIST"] = "docker.io/sprisa/opencode:2.2.4,docker.io/sprisa/opencode:1.19.5"
+ self.run_command("task", "publish", "FORCE=true")
+ self.assertEqual(len(self.builds()), 2)
self.assertFalse(any(args[:2] == ["release", "create"] for args in self.calls("gh")))
def test_release_notes_select_only_older_tags_in_current_history(self):
diff --git a/test-server-e2e.sh b/tests/test-server-e2e.sh
similarity index 98%
rename from test-server-e2e.sh
rename to tests/test-server-e2e.sh
index c49a32b..0eb13d5 100644
--- a/test-server-e2e.sh
+++ b/tests/test-server-e2e.sh
@@ -1,8 +1,8 @@
#!/usr/bin/env bash
-# Exercise the real, major-specific entrypoint. Usage: bash test-server-e2e.sh
+# Exercise the real, major-specific entrypoint. Usage: bash tests/test-server-e2e.sh
set -euo pipefail
-IMAGE="${1:?usage: test-server-e2e.sh }"
+IMAGE="${1:?usage: tests/test-server-e2e.sh }"
NAME="opencode-server-e2e-$$"
PORT=4186
VERSION="$(docker image inspect -f '{{index .Config.Labels "org.opencontainers.image.version"}}' "$IMAGE")"
diff --git a/tests/test-toolchain-e2e.sh b/tests/test-toolchain-e2e.sh
new file mode 100644
index 0000000..a8be545
--- /dev/null
+++ b/tests/test-toolchain-e2e.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Exercise the pinned package managers and their real install paths.
+# Usage: bash tests/test-toolchain-e2e.sh
+set -euo pipefail
+
+IMAGE="${1:?usage: tests/test-toolchain-e2e.sh }"
+NAME="opencode-toolchain-e2e-$$"
+cleanup() { docker rm -f "$NAME" >/dev/null 2>&1 || true; }
+trap cleanup EXIT
+
+echo "Testing package managers and lazy installs (${IMAGE}; 5-minute timeout)..."
+docker run --rm -i --name "$NAME" -e GITHUB_TOKEN --entrypoint timeout "$IMAGE" 300 bash -s <<'TEST'
+set -euo pipefail
+
+brew --version
+mise --version
+zb --version
+git -C /opt/mise/plugins/zerobrew rev-parse HEAD
+
+# These commands must start lazy and then install via the zerobrew plugin,
+# including its per-tool root initialization and runtime library paths.
+for command in wget nano; do
+ [ "$(command -v "$command")" = "/opt/auto-install-shims/$command" ]
+done
+wget --version
+nano --version
+
+# Ruby comes from mise core as a precompiled build (ruby.compile = false).
+# Regression: the old zerobrew Ruby passed `ruby --version` but looked for its
+# standard library under the Homebrew Cellar, so every require and gem failed.
+# Check the stdlib dirs exist, load stdlib and native libraries, and install
+# and load a gem.
+[ "$(command -v ruby)" = "/opt/auto-install-shims/ruby" ]
+ruby -e '
+ require "rbconfig"
+ dirs = RbConfig::CONFIG.values_at("rubylibdir", "archdir")
+ missing = dirs.reject { |dir| File.directory?(dir) }
+ abort "missing Ruby stdlib dirs: #{missing.join(", ")}" unless missing.empty?
+ %w[json openssl psych].each { |lib| require lib }
+ puts RUBY_DESCRIPTION
+'
+gem install --no-document rainbow
+ruby -rrainbow -e 'puts Rainbow("gem install ok").green'
+bundle --version
+
+# Also exercise Homebrew itself and the standalone zbx wrapper, rather than
+# only checking that the pinned package-manager executables start.
+brew install hello
+hello --version
+zbx hello --version
+TEST
+
+echo "PASS: Homebrew, mise, zerobrew plugin and mise core lazy installs, and zbx ($IMAGE)"