Skip to content

feat: lock mise tools at build time; add Codex, Claude Code, clonetree and cloudflared; rewrite README - #87

Merged
gabemeola merged 1 commit into
mainfrom
pr87
Nov 13, 2026
Merged

gabemeola merged 1 commit into
mainfrom
pr87

Conversation

@gabemeola

Copy link
Copy Markdown
Member

Summary

  • New lazy-installed tools: Codex (codex), Claude Code (claude), clonetree (clonetree) and cloudflared (cloudflared).
  • Tools moved to mise core: gh, jq, ripgrep, fd, micro and Ruby. They used the github or zerobrew backends before.
  • Build-time lockfile: each image locks its mise tools when it's built, so first runs skip the version lookup.
  • Fixed Ruby: the old zerobrew Ruby couldn't load its own standard library.
  • README rewrite for newcomers, with Kubernetes and Claude/ChatGPT sign-in sections.
  • Tests moved to tests/, plus a new lockfile regression test.

Tools

The new tools install on first use, like the rest:

Tool Command Backend
Codex codex mise core
Claude Code claude mise core
cloudflared cloudflared mise core
clonetree clonetree github (not in the mise registry)

These tools moved from github or zerobrew to mise core, the same tools under their mise registry names:

  • gh, jq, ripgrep, fd and micro, from github
  • Ruby, from zerobrew

wget, nano and Sapling stay where they were, because the mise registry doesn't have them.

Ruby was broken under zerobrew

ruby --version worked, but Ruby looked for its standard library under the Homebrew Cellar, which doesn't exist in the image. So every require failed, including json and rbconfig, and so did every gem command. Ruby now comes from mise core as a prebuilt build, with ruby.compile = false because the image has no compiler. Prebuilt gems such as nokogiri install normally. Gems that compile native code need sudo apt-get install build-essential first.

Build-time lockfile

Adding Codex exposed a problem. Codex's release list is about 10 MB: it has 87 prereleases among its last 100 releases and about 236 files per release. Downloading it takes around 11 seconds, and mise gives up after 3. Because mise resolves every latest entry in the config on a tool's first run, the Codex lookup slowed every tool:

First run in a fresh container Before After
jq 8.4s 0.6s
gh (no GITHUB_TOKEN) 7.9s 0.8s
codex hung past 90s 3.7s

The Dockerfile now runs mise lock -g at build time and writes /etc/mise/mise.lock. That records the newest release of each latest tool, with its download URL and checksum. At runtime, mise downloads straight from the locked URL, with no version lookup and no GitHub API calls.

  • mise-config.toml still says latest. Each new image locks the newest releases. An older image keeps the versions from its own build and never goes back to looking them up.
  • The lock step references OPENCODE_VERSION, so each opencode release builds a new lock instead of reusing a cached layer. To refresh tool versions without changing the opencode version, build with --no-cache.
  • The opencode user owns /etc/mise, because mise writes a temp file next to the lockfile whenever it checks it.
  • Tools the image doesn't ship (mise use go, a project's own mise.toml) resolve latest at runtime as before, and don't create lockfiles.
  • For tools the image does ship, a bare mise use jq keeps the image's locked version. mise use jq@latest and mise upgrade jq get the newest release. The README and the agent instruction file explain this.

README

  • Rewritten to read top to bottom: what the image is, a quick start, tools, configuration, deploying, versions, and development.
  • Quick start: keeps the original -v $(pwd):/home/opencode command. It adds a two-mount option for working on an existing project without writing opencode's files into it.
  • New Kubernetes section, noting that we run this image in production for Codeplace. It covers storage, fsGroup: 1000, passing the password from a Secret, and TCP probes.
  • New "Use your Claude or ChatGPT subscription" section:
    • Claude: run claude auth login in opencode's web terminal, then connect the Claude agent in the UI.
    • ChatGPT: use opencode's device code sign-in, after turning on Enable device code sign-in for Codex, Excel, PowerPoint, and Word in ChatGPT's App security settings.
  • Fixed stale or incorrect docs:
    • Removed n <version>, which isn't in the image.
    • v1 images only read OPENCODE_SERVER_PASSWORD.
    • v1 log levels are uppercase.
    • A generated password changes on every restart.

Tests

  • Moved all test scripts to tests/ and updated pr-test.yml to match.
  • New tests/test-mise-lock-e2e.sh, which runs without GITHUB_TOKEN on purpose. It checks that:
    • every mise core and github tool is locked to an exact version;
    • jq, codex, gh and clonetree install their locked versions on first run with no version lookup, and the lockfile doesn't change;
    • a bare mise use shellcheck resolves the newest release and writes no lockfile;
    • on a simulated old image, the locked version is used with no lookup, a bare mise use jq keeps it, and mise use jq@latest and mise upgrade jq get the newest release;
    • a bare mise upgrade upgrades the image's tools and rewrites the lockfile.
  • Ruby regression check in test-toolchain-e2e.sh: it checks that Ruby's standard library folders exist, loads json, openssl and psych, installs and loads a gem, and runs bundle --version. It fails on the old zerobrew Ruby.
  • New CI check that the new tools are set up to install on first use.

Testing

Run locally on arm64 against a fresh build:

  • tests/test-release-automation.py and tests/test-bump-version.sh pass.
  • The server, toolchain, home-tools and mise-lock e2e tests pass.
  • The lockfile test fails on an image built without the lockfile. Run by hand on that image, its lookup check flagged 87 lookup requests on jq's first run.
  • Each tool installed and ran on first use.
  • A cloudflared quick tunnel served a page through its public trycloudflare.com URL.
  • claude auth login prints a sign-in link and accepts a pasted code inside the container.

CI covers amd64.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Docker image size comparison

Image Size
Baseline (main) 1.17GB
This PR 1.17GB
Difference +17KB

…e and cloudflared; rewrite README

## Summary

- **New lazy-installed tools:** Codex (`codex`), Claude Code (`claude`), clonetree (`clonetree`) and cloudflared (`cloudflared`).
- **Tools moved to mise core:** gh, jq, ripgrep, fd, micro and Ruby. They used the `github` or `zerobrew` backends before.
- **Build-time lockfile:** each image locks its mise tools when it's built, so first runs skip the version lookup.
- **Fixed Ruby:** the old zerobrew Ruby couldn't load its own standard library.
- **README rewrite** for newcomers, with Kubernetes and Claude/ChatGPT sign-in sections.
- **Tests moved to `tests/`,** plus a new lockfile regression test.

## Tools

The new tools install on first use, like the rest:

| Tool | Command | Backend |
|---|---|---|
| Codex | `codex` | mise core |
| Claude Code | `claude` | mise core |
| cloudflared | `cloudflared` | mise core |
| clonetree | `clonetree` | github (not in the mise registry) |

These tools moved from `github` or `zerobrew` to mise core, the same tools under their mise registry names:

- gh, jq, ripgrep, fd and micro, from `github`
- Ruby, from `zerobrew`

wget, nano and Sapling stay where they were, because the mise registry doesn't have them.

### Ruby was broken under zerobrew

`ruby --version` worked, but Ruby looked for its standard library under the Homebrew Cellar, which doesn't exist in the image. So every `require` failed, including `json` and `rbconfig`, and so did every `gem` command. Ruby now comes from mise core as a prebuilt build, with `ruby.compile = false` because the image has no compiler. Prebuilt gems such as nokogiri install normally. Gems that compile native code need `sudo apt-get install build-essential` first.

## Build-time lockfile

Adding Codex exposed a problem. Codex's release list is about 10 MB: it has 87 prereleases among its last 100 releases and about 236 files per release. Downloading it takes around 11 seconds, and mise gives up after 3. Because mise resolves every `latest` entry in the config on a tool's first run, the Codex lookup slowed every tool:

| First run in a fresh container | Before | After |
|---|---|---|
| `jq` | 8.4s | 0.6s |
| `gh` (no `GITHUB_TOKEN`) | 7.9s | 0.8s |
| `codex` | hung past 90s | 3.7s |

The Dockerfile now runs `mise lock -g` at build time and writes `/etc/mise/mise.lock`. That records the newest release of each `latest` tool, with its download URL and checksum. At runtime, mise downloads straight from the locked URL, with no version lookup and no GitHub API calls.

- **`mise-config.toml` still says `latest`.** Each new image locks the newest releases. An older image keeps the versions from its own build and never goes back to looking them up.
- **The lock step references `OPENCODE_VERSION`,** so each opencode release builds a new lock instead of reusing a cached layer. To refresh tool versions without changing the opencode version, build with `--no-cache`.
- **The `opencode` user owns `/etc/mise`,** because mise writes a temp file next to the lockfile whenever it checks it.
- **Tools the image doesn't ship** (`mise use go`, a project's own `mise.toml`) resolve `latest` at runtime as before, and don't create lockfiles.
- **For tools the image does ship,** a bare `mise use jq` keeps the image's locked version. `mise use jq@latest` and `mise upgrade jq` get the newest release. The README and the agent instruction file explain this.

## README

- **Rewritten to read top to bottom:** what the image is, a quick start, tools, configuration, deploying, versions, and development.
- **Quick start:** keeps the original `-v $(pwd):/home/opencode` command. It adds a two-mount option for working on an existing project without writing opencode's files into it.
- **New Kubernetes section,** noting that we run this image in production for Codeplace. It covers storage, `fsGroup: 1000`, passing the password from a Secret, and TCP probes.
- **New "Use your Claude or ChatGPT subscription" section:**
  - **Claude:** run `claude auth login` in opencode's web terminal, then connect the Claude agent in the UI.
  - **ChatGPT:** use opencode's device code sign-in, after turning on **Enable device code sign-in for Codex, Excel, PowerPoint, and Word** in ChatGPT's App security settings.
- **Fixed stale or incorrect docs:**
  - Removed `n <version>`, which isn't in the image.
  - v1 images only read `OPENCODE_SERVER_PASSWORD`.
  - v1 log levels are uppercase.
  - A generated password changes on every restart.

## Tests

- **Moved all test scripts to `tests/`** and updated `pr-test.yml` to match.
- **New `tests/test-mise-lock-e2e.sh`,** which runs without `GITHUB_TOKEN` on purpose. It checks that:
  - every mise core and github tool is locked to an exact version;
  - `jq`, `codex`, `gh` and `clonetree` install their locked versions on first run with no version lookup, and the lockfile doesn't change;
  - a bare `mise use shellcheck` resolves the newest release and writes no lockfile;
  - on a simulated old image, the locked version is used with no lookup, a bare `mise use jq` keeps it, and `mise use jq@latest` and `mise upgrade jq` get the newest release;
  - a bare `mise upgrade` upgrades the image's tools and rewrites the lockfile.
- **Ruby regression check in `test-toolchain-e2e.sh`:** it checks that Ruby's standard library folders exist, loads `json`, `openssl` and `psych`, installs and loads a gem, and runs `bundle --version`. It fails on the old zerobrew Ruby.
- **New CI check** that the new tools are set up to install on first use.

## Testing

Run locally on arm64 against a fresh build:

- `tests/test-release-automation.py` and `tests/test-bump-version.sh` pass.
- The server, toolchain, home-tools and mise-lock e2e tests pass.
- The lockfile test fails on an image built without the lockfile. Run by hand on that image, its lookup check flagged 87 lookup requests on `jq`'s first run.
- Each tool installed and ran on first use.
- A cloudflared quick tunnel served a page through its public `trycloudflare.com` URL.
- `claude auth login` prints a sign-in link and accepts a pasted code inside the container.

CI covers amd64.
@gabemeola
gabemeola merged commit 0f66006 into main Nov 13, 2026
8 checks passed
@gabemeola
gabemeola deleted the pr87 branch November 13, 2026 22:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant