Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Add shared Codex Cloud environment setup (#3810)

Maximilian Roos18b408ce9848
diff --git a/.claude/skills/running-tend/SKILL.md b/.claude/skills/running-tend/SKILL.md
index 2126d7964..7834702ac 100644
--- a/.claude/skills/running-tend/SKILL.md
+++ b/.claude/skills/running-tend/SKILL.md
@@ -301,6 +301,7 @@ For each weekly run, check upstream and bump:
- **`baptiste0928/cargo-install@v3` blocks** in `.github/workflows/{affected,ci,coverage,nightly}.yaml` and `.github/actions/{test,claude}-setup/action.yaml` — every `version: "=X.Y.Z"` against `cargo info <crate>`. Today: `cargo-affected`, `cargo-insta`, `cargo-nextest`, `cargo-llvm-cov`, `cargo-msrv`, `cargo-udeps`, `lychee`, `worktrunk`. `cargo-affected` is pinned twice in `affected.yaml`; move both together. Verify each crate's `rust-version` against the pinned toolchain and note compatibility in the PR body (see PR #1657 for the format).
- **`hustcer/setup-nu@v3`** `version:` input — latest from `gh api repos/nushell/nushell/releases/latest --jq '.tag_name'`. Four call sites: `coverage.yaml` (`code-coverage`), `nightly.yaml` (`feature-powerset`), `benchmarks.yaml` (`benchmarks`), and `actions/test-setup/action.yaml`.
+- **Codex Cloud tools** — `scripts/codex-cloud/Taskfile.yaml` pins Task through mise, pre-commit through uv, and cargo-insta, cargo-nextest, Nushell, and PowerShell archives with SHA-256 checksums. Keep overlapping versions aligned with CI and `setup-web`, update changed archive checksums, then copy the Taskfile's new digest into both README launchers.
- **`taiki-e/[email protected]`** `tool: zola@<ver>` in the `check-docs` job — latest from `gh api repos/getzola/zola/releases/latest --jq '.tag_name'`.
- **Runner images** — `ubuntu-24.04`, `macos-15`, `windows-2022`. Keep `windows-2022` pinned (actions/runner-images#12677 — windows-2025 lacks the D: drive).
diff --git a/CLAUDE.md b/CLAUDE.md
index 7485d0900..c7a1d4fb6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,6 +7,7 @@ cargo run -- hook pre-merge --yes # all tests + lints (runs automatically in w
```
Claude Code web: run `task setup-web` first. Test commands, isolation, and coverage investigation: `tests/CLAUDE.md`.
+Codex Cloud: use the checksum-gated setup in `scripts/codex-cloud/README.md`.
## Project Status
diff --git a/Taskfile.yaml b/Taskfile.yaml
index 97c848d13..7e6d55a71 100644
--- a/Taskfile.yaml
+++ b/Taskfile.yaml
@@ -26,6 +26,16 @@ tasks:
- bash -c 'time "$@"' bash cargo nextest run --features shell-integration-tests {{.CLI_ARGS}}
- echo "per-test timings in target/nextest/default/junit.xml"
+ setup-codex:
+ desc: Setup Codex Cloud universal image (root only)
+ platforms: [linux]
+ cmd: task --taskfile scripts/codex-cloud/Taskfile.yaml setup-codex
+
+ maintain-codex:
+ desc: Maintain Codex Cloud universal image (root only)
+ platforms: [linux]
+ cmd: task --taskfile scripts/codex-cloud/Taskfile.yaml maintain-codex
+
setup-web:
desc: Setup Claude Code web environment for development
platforms: [linux]
diff --git a/scripts/codex-cloud/README.md b/scripts/codex-cloud/README.md
new file mode 100644
index 000000000..767e7716d
--- /dev/null
+++ b/scripts/codex-cloud/README.md
@@ -0,0 +1,30 @@
+# Codex Cloud
+
+The environment uses the `universal` image, caching, unrestricted internet,
+and no variables or secrets.
+
+Setup command:
+
+```bash
+TASKFILE_SHA=abce64dd8aea02ba4dc9d8e8a5c6837c3b8937c4fec4d213373593ec6b0eb05e; printf '%s %s\n' "$TASKFILE_SHA" scripts/codex-cloud/Taskfile.yaml | sha256sum -c - && MISE_NO_CONFIG=1 MISE_HTTP_RETRIES=6 mise x [email protected] -- task -t scripts/codex-cloud/Taskfile.yaml setup-codex
+```
+
+Maintenance command:
+
+```bash
+TASKFILE_SHA=abce64dd8aea02ba4dc9d8e8a5c6837c3b8937c4fec4d213373593ec6b0eb05e; printf '%s %s\n' "$TASKFILE_SHA" scripts/codex-cloud/Taskfile.yaml | sha256sum -c - && MISE_NO_CONFIG=1 MISE_HTTP_RETRIES=6 mise x [email protected] -- task -t scripts/codex-cloud/Taskfile.yaml maintain-codex
+```
+
+The hash prevents a task branch from changing code run as root. After a reviewed
+Taskfile change reaches the default branch, update both environment commands;
+the settings change invalidates the cache.
+
+The agent remains root. Toolchain-sensitive Rustup and pre-commit steps run as
+`ubuntu`; the Cargo wrapper also runs builds and tests as `ubuntu` under `tini`,
+matching the suite's permission and child-reaping assumptions.
+
+Validation:
+
+```bash
+cargo run -- hook pre-merge --yes
+```
diff --git a/scripts/codex-cloud/Taskfile.yaml b/scripts/codex-cloud/Taskfile.yaml
new file mode 100644
index 000000000..6e2e5a2fa
--- /dev/null
+++ b/scripts/codex-cloud/Taskfile.yaml
@@ -0,0 +1,151 @@
+version: "3"
+
+vars:
+ CODEX_REPO_ROOT: "{{.TASKFILE_DIR}}/../.."
+ TASK_VERSION: "3.52.0"
+ PRE_COMMIT_VERSION: "4.6.1"
+ INSTA_VERSION: "1.48.0"
+ NEXTEST_VERSION: "0.9.143"
+ NU_VERSION: "0.114.1"
+ PWSH_VERSION: "7.6.4"
+
+tasks:
+ setup-codex:
+ desc: Setup Codex Cloud universal image (root only)
+ platforms: [linux]
+ dir: "{{.CODEX_REPO_ROOT}}"
+ preconditions:
+ - sh: test "$(id -u)" = 0 && test "$(id -u ubuntu 2>/dev/null)" = 1000
+ msg: Codex Cloud setup requires root and the universal image's ubuntu user
+ env:
+ DEBIAN_FRONTEND: noninteractive
+ MISE_HTTP_RETRIES: 6
+ MISE_NO_CONFIG: "1"
+ cmds:
+ - |
+ set -euo pipefail
+
+ apt-get update -qq
+ apt-get install -y -qq --no-install-recommends software-properties-common
+ add-apt-repository -y ppa:git-core/ppa
+ apt-get update -qq
+ apt-get install -y -qq --no-install-recommends git zsh fish xz-utils lsof tini
+
+ mise use --global task@{{.TASK_VERSION}}
+ uv tool install pre-commit=={{.PRE_COMMIT_VERSION}}
+ install -d /root/.local/bin
+
+ tools_tmp="$(mktemp -d)"
+ download() {
+ curl -fsSL --retry 6 --retry-all-errors --retry-delay 2 \
+ "$1" -o "$tools_tmp/$3"
+ printf '%s %s\n' "$2" "$tools_tmp/$3" | sha256sum -c -
+ }
+ install_binary() {
+ download "$1" "$2" "$3"
+ case "$3" in
+ *.tar.xz) tar -xJf "$tools_tmp/$3" -C "$tools_tmp" ;;
+ *.tar.gz) tar -xzf "$tools_tmp/$3" -C "$tools_tmp" ;;
+ esac
+ install -m 0755 "$tools_tmp/$4" "$5"
+ }
+
+ install_binary \
+ https://github.com/mitsuhiko/insta/releases/download/{{.INSTA_VERSION}}/cargo-insta-x86_64-unknown-linux-gnu.tar.xz \
+ 1c05a480a5a7f755f0ea15b2d8e2f71ad51b9c3a270d38ac72005c57ac0a1487 \
+ cargo-insta.tar.xz cargo-insta-x86_64-unknown-linux-gnu/cargo-insta \
+ /root/.local/bin/cargo-insta
+ install_binary \
+ https://github.com/nextest-rs/nextest/releases/download/cargo-nextest-{{.NEXTEST_VERSION}}/cargo-nextest-{{.NEXTEST_VERSION}}-x86_64-unknown-linux-gnu.tar.gz \
+ 66786b9abe23920d022a182d1416b1bbc8130dd4872a9553d76985a1708dcd1e \
+ cargo-nextest.tar.gz cargo-nextest /root/.local/bin/cargo-nextest
+ install_binary \
+ https://github.com/nushell/nushell/releases/download/{{.NU_VERSION}}/nu-{{.NU_VERSION}}-x86_64-unknown-linux-gnu.tar.gz \
+ 8802b26edcdf1a64477567b5ce909fbae3d72d731c8f0847892ea16c6fa73c53 \
+ nu.tar.gz nu-{{.NU_VERSION}}-x86_64-unknown-linux-gnu/nu /root/.local/bin/nu
+
+ pwsh_archive=powershell.tar.gz
+ # The universal image supplies libicu; the version probe below fails if that changes.
+ download \
+ https://github.com/PowerShell/PowerShell/releases/download/v{{.PWSH_VERSION}}/powershell-{{.PWSH_VERSION}}-linux-x64.tar.gz \
+ 4471b5a36bfe86ec7af8525d36bb1cacba0128e7aac22d05cc064bc00e604721 \
+ "$pwsh_archive"
+ install -d /opt/microsoft/powershell/7
+ tar -xzf "$tools_tmp/$pwsh_archive" -C /opt/microsoft/powershell/7
+ chmod 0755 /opt/microsoft/powershell/7/pwsh
+ ln -sf /opt/microsoft/powershell/7/pwsh /usr/local/bin/pwsh
+ rm -r -- "$tools_tmp"
+
+ git_version="$(git version | awk '{print $3}')"
+ dpkg --compare-versions "$git_version" ge 2.54.0
+ chmod 0711 /root
+ chown -hR ubuntu:ubuntu "$PWD"
+ git config --system --add safe.directory "$PWD"
+
+ rm /root/.cargo/bin/cargo
+ install -m 0755 /dev/stdin /root/.cargo/bin/cargo <<'CARGO_WRAPPER'
+ #!/bin/sh
+ set -eu
+
+ if [ "$(id -u)" -ne 0 ]; then
+ if [ "${CODEX_CARGO_IDENTITY_PROBE:-0}" = 1 ]; then
+ exec /usr/bin/id -u
+ fi
+ cargo_path="$(/root/.cargo/bin/rustup which cargo)"
+ toolchain_bin="${cargo_path%/cargo}"
+ PATH="$toolchain_bin:/root/.local/bin:/root/.local/share/mise/installs/task/{{.TASK_VERSION}}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+ export PATH
+ exec "$cargo_path" "$@"
+ fi
+
+ exec /usr/bin/tini -s -- /usr/sbin/runuser -u ubuntu -- \
+ /usr/bin/env HOME=/home/ubuntu USER=ubuntu LOGNAME=ubuntu \
+ CARGO_HOME=/root/.cargo RUSTUP_HOME=/root/.rustup \
+ PRE_COMMIT_HOME=/root/.cache/pre-commit PATH="$PATH" \
+ CODEX_CARGO_IDENTITY_PROBE="${CODEX_CARGO_IDENTITY_PROBE:-0}" \
+ /root/.cargo/bin/cargo "$@"
+ CARGO_WRAPPER
+
+ for executable in task pre-commit cargo cargo-insta cargo-nextest git lsof pwsh tini zsh fish nu; do
+ command -v "$executable" >/dev/null
+ done
+ test -x /root/.local/share/mise/installs/task/{{.TASK_VERSION}}/task
+ pwsh -NoLogo -NoProfile -Command '$PSVersionTable.PSVersion.ToString()'
+ - task: prepare-codex
+
+ maintain-codex:
+ desc: Maintain Codex Cloud universal image (root only)
+ platforms: [linux]
+ preconditions:
+ - sh: test "$(id -u)" = 0 && test "$(id -u ubuntu 2>/dev/null)" = 1000
+ msg: Codex Cloud maintenance requires root and the universal image's ubuntu user
+ cmds:
+ - task: prepare-codex
+
+ prepare-codex:
+ internal: true
+ dir: "{{.CODEX_REPO_ROOT}}"
+ cmds:
+ - |
+ set -euo pipefail
+
+ chown -R ubuntu:ubuntu /root/.rustup
+ install -d -m 0755 -o ubuntu -g ubuntu target \
+ /root/.cargo/registry /root/.cargo/git /root/.cache/pre-commit
+ find "$PWD" -path "$PWD/target" -prune -o -exec chown -h ubuntu:ubuntu {} +
+ for cache_dir in /root/.cargo/registry /root/.cargo/git /root/.cache/pre-commit; do
+ [ ! -e "$cache_dir" ] || chown -R ubuntu:ubuntu "$cache_dir"
+ done
+ /usr/sbin/runuser -u ubuntu -- \
+ /usr/bin/env HOME=/home/ubuntu USER=ubuntu LOGNAME=ubuntu \
+ RUSTUP_HOME=/root/.rustup \
+ /root/.cargo/bin/rustup component add rust-docs
+ /usr/sbin/runuser -u ubuntu -- \
+ /usr/bin/env HOME=/home/ubuntu USER=ubuntu LOGNAME=ubuntu \
+ CARGO_HOME=/root/.cargo RUSTUP_HOME=/root/.rustup \
+ PRE_COMMIT_HOME=/root/.cache/pre-commit PATH="$PATH" \
+ pre-commit install-hooks
+ test "$(command -v cargo)" = /root/.cargo/bin/cargo
+ test "$(CODEX_CARGO_IDENTITY_PROBE=1 cargo)" = 1000
+ cargo --version
+ cargo fetch --locked
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 968d63144..1826ef4e5 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1572,6 +1572,36 @@ fn test_taskfile_llm_commands_match_config_example() {
);
}
+#[test]
+fn test_codex_cloud_launchers_match_taskfile() {
+ use sha2::{Digest, Sha256};
+
+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ let taskfile = fs::read(project_root.join("scripts/codex-cloud/Taskfile.yaml")).unwrap();
+ let taskfile_text = std::str::from_utf8(&taskfile).unwrap();
+ let readme = fs::read_to_string(project_root.join("scripts/codex-cloud/README.md")).unwrap();
+
+ let digest: String = Sha256::digest(&taskfile)
+ .iter()
+ .map(|byte| format!("{byte:02x}"))
+ .collect();
+ let task_version = Regex::new(r#"(?m)^ TASK_VERSION: "([^"]+)"$"#)
+ .unwrap()
+ .captures(taskfile_text)
+ .unwrap()[1]
+ .to_string();
+
+ for task in ["setup-codex", "maintain-codex"] {
+ let launcher = format!(
+ "TASKFILE_SHA={digest}; printf '%s %s\\n' \"$TASKFILE_SHA\" scripts/codex-cloud/Taskfile.yaml | sha256sum -c - && MISE_NO_CONFIG=1 MISE_HTTP_RETRIES=6 mise x task@{task_version} -- task -t scripts/codex-cloud/Taskfile.yaml {task}"
+ );
+ assert!(
+ readme.lines().any(|line| line == launcher),
+ "Codex Cloud {task} launcher in scripts/codex-cloud/README.md is stale; replace it with:\n{launcher}"
+ );
+ }
+}
+
#[test]
fn test_config_source_templates_are_in_sync() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));