mbx puts a content-addressed rustc cache behind ordinary Cargo commands.
Cargo still resolves dependencies, plans builds, and links outputs. mbx
restores the compilations it has seen before. Run mbx setup once and keep
using the Cargo commands you already run.
Why mbx?
- Cache keys contain no checkout-specific paths, so building one worktree warms its siblings, and no two checkouts wait on the same Cargo target lock.
- Disk use is bounded without a chore. The cache prunes itself to a share of
the disk, and a managed
target/directory is deleted when its checkout is gone, unused for 30 days, or over budget. - Several Cargo builds can run at once. They share one machine-wide CPU and memory budget, and a cold compilation already running in one build is compiled once and restored into the others.
- CI can be warmed safely. GitHub Actions cache can warm fork pull requests
from a cache built on
main, and pull requests never publish remote objects. - The summary counts hits, misses, and the compilations mbx could not look up or bypassed on purpose, so a high hit rate cannot hide work that never entered the cache.
Install
With mise:
[!NOTE] Automatic Cargo wrapping requires mise 2026.8.16 or newer.
Open a new shell and check that command -v cargo resolves to mise's command
wrapper. mbx setup writes a [wrappers.cargo] entry and runs mise reshim.
Tools that skip mise activation, such as SSH commands and coding agents, need
~/.local/share/mbx/bin on PATH instead. Prefixing a command with mbx
always works.
With Cargo:
Release archives for Linux, macOS, and Windows are on the
releases page, each with a
SHA256SUMS file.
See all installation options →
Automatic pruning
Collection runs after a build, at most once an hour, and needs no configuration. The first build prints the budgets it chose for this machine. mbx keeps a running total of what collection has reclaimed and prints one line about it after a build:
mbx[savings]: 41.7 GiB of target/ had outlived its checkouts. it has been dealt with.
savings = "plain" drops the joke. Inspect or collect the store by hand with:
For a checkout without an existing target/, the first build places the
target directory under the cache root and leaves target as a symlink, so
familiar paths still work and a deleted checkout's outputs get collected. An
existing target/ is only replaced if you say yes at the prompt.
CI
For GitHub-hosted CI, jdx/mr-boxington-action
installs mbx and uses GitHub Actions cache. Trusted environments can point the
same action at a compatible remote such as the self-hostable
cache server.
Parallel steps that run Clippy and tests together can each get their own
CARGO_TARGET_DIR and share one CPU and memory budget through mbx. mise's
lint job finished up to 45% sooner this way.
How it works
An mbx Cargo command starts an in-process cache agent, points Cargo at rustc
and rustdoc shims, and stops the agent when the build ends. There is no daemon.
The shims derive action keys, restore cached outputs when they can, and
otherwise run the real tool and publish a successful result.
Anything mbx cannot model exactly bypasses the cache. Native links are cached on Linux, macOS, and Windows when mbx can put the linker and its system inputs into the key, and the workspace crate you are editing is recompiled incrementally with state that never enters the shared cache.
Read the architecture and limits →
Documentation
- Get started
- Configuration
- GitHub Action
- Benchmarks
- Remote cache
- Protocol compatibility
- Cache results
- Watching builds
- CLI reference
- Current limits
Acknowledgements
mbx relies on Cargo and follows earlier compiler-cache work in sccache and kache, which directly inspired its design. Read the acknowledgements.