How to Fix mise Version Pinning Not Working on Codex Cloud

mise install bun succeeded, yet bun came back as command not found. This happened while using mise on Codex Cloud.

I had been relying on .tool-versions to pin versions locally and assumed it would just work. It didn’t carry over to the Cloud.

Symptoms

The pinned bun and node versions drift on the Cloud. mise install bun succeeds, but running bun right after fails with not found. Dependencies can also break after cache restoration.

If any of these are happening, there’s a good chance you’re conflating mise’s install step with shell activation.

Cause

Codex Cloud does not automatically apply .tool-versions or .mise.toml. Leave it alone like you would locally, and nothing works.

The biggest trap is how mise install behaves. mise install bun only downloads the binary—it does not add it to the shell’s PATH. You need to run mise activate or mise exec separately. Without knowing this, command not found keeps coming back no matter how many times you retry.

Writing “use bun” in AGENTS.md only serves as a policy hint. It does not control environment setup itself.

Fixing It with setup.sh and maintenance.sh

Switch the Codex Cloud Environment to Manual setup and write the setup scripts yourself.

.tool-versions

bun 1.3.8
nodejs 25.6.0

.codex/cloud/setup.sh

#!/usr/bin/env bash

set -euo pipefail

mise use -g bun@1.3.8
mise use -g node@25.6.0

eval "$(mise activate bash --shims)"
bun install --frozen-lockfile

mise use -g registers the tools globally, then mise activate bash --shims makes them available through shims on the PATH. Splitting these into two steps is the key. Trying to do everything with a single mise install will fail.

.codex/cloud/maintenance.sh

#!/usr/bin/env bash

set -euo pipefail

bun install --frozen-lockfile

This script runs after cache restoration. It assumes the PATH configured by setup.sh is still in place.

Operational Steps

Enable Manual setup in the Codex Cloud Environment settings and point the setup script to .codex/cloud/setup.sh and the maintenance script to .codex/cloud/maintenance.sh. Reset and recreate the Environment cache to apply the changes.

As an auxiliary measure, add Use bun for install/run. Do not use npm unless explicitly requested. to AGENTS.md.

Gotchas

mise install alone will not make bun executable. mise activate or mise exec is required. Unless you build your configuration around the premise that install and shell activation are separate steps, you’ll hit the same wall.

The setup script and subsequent processes run in separate sessions. PATH-dependent settings are better kept self-contained within each script. If bun is not found in the maintenance script, mise exec -- bun ... can work around it.

Wrap-up

To stabilize mise on Codex Cloud, prepare your own setup.sh and maintenance.sh under Manual setup, and wire the PATH through mise use -g combined with mise activate. Don’t try to get by with mise install alone.

Once Codex Cloud supports custom Docker images, this entire workaround may become unnecessary.