mbx is a build cache for Rust projects. Cargo still resolves dependencies,
plans builds, and runs your tools. mbx restores matching compiler outputs from
one shared store and compiles the rest. Each command starts its own cache
agent and stops it when the build ends; there is no daemon to manage.
Get started
With mise:
mise use --global --tool-option mr_boxington=true rust mr-boxington
Or with Cargo:
cargo install mbx --locked
mbx setup
With mise 2026.9.2 or newer, the mr_boxington Rust option wraps Cargo
without an mbx setup hook. Open a shell with mise activation or shims on
PATH, check Cargo's path,
and use Cargo normally:
cargo build
cargo test --workspace --all-features
cargo clippy --workspace --all-targets -- -D warnings
Interactive builds use cargo-pretty's
display by romancitodev, extended with mbx cache information. Follow live and
completed crates, browse warnings and test failures, and see cache hits, misses,
bypasses, and estimated compiler time saved. The build bar doubles as a cache
breakdown: green for hits, yellow for misses, and grey for bypasses and
compilations not looked up.
Cargo remains in charge of run, tests, doctests, and configured runners. CI,
redirected output, and explicit output formats keep Cargo's normal output.
Set MBX_DISPLAY=plain, or run mbx settings set display plain, to turn the
display off.
View the still image.
To try mbx without automatic wrapping, install it and run mbx build directly.
For coding agents and other non-interactive tools, use mise exec -- cargo build
or put mise's shims on their PATH. The
setup guide covers desktop applications
and standalone setup with the Cargo shim. For mise older than 2026.9.2, see
Older mise versions.
Verified release archives are available for Linux, macOS, and Windows.
All installation options →
What you get
- Reuse across worktrees. Equivalent compilations share cache keys even
when checkout paths differ. Building one worktree warms the next.
- Automatic cleanup. The store has a disk budget. Managed target
directories are collected when their checkout disappears, they go unused, or
they exceed their budget. Preview collection with
mbx gc --dry-run.
- Parallel builds with a shared budget. Independent Cargo commands share
CPU and memory permits and deduplicate identical compilations in flight.
Give each build its own target directory to avoid Cargo's directory lock;
check and clippy already get a
check lane of
their own.
- Faster local edits. mbx keeps private incremental state for crates you
are changing while sharing eligible work across the rest of the build.
- CI reuse. Use the GitHub Actions cache, a compatible cache server, or an
S3-compatible bucket. mbx writes to a cache server or bucket only from
pushes to protected branches, so pull request builds only read from it.
- An explanation for each result. The build summary counts each kind of
cache result separately: hits,
misses, bypasses, and compilations not looked up.
mbx explain --last
diagnoses this workspace's last recorded build.
A cold store needs a build to fill it. Unsupported invocations run normally
without caching, and restored debug information can retain the original
checkout's paths. See how it works
and the caching limits.
Use it in GitHub Actions
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: jdx/mr-boxington-action@v1
- run: mbx test --workspace
Install your chosen Rust toolchain before the cache action. The action's
default github backend restores a pruned Cargo target directory and registry
from the GitHub Actions cache. It saves a new entry after a successful run for
a push to the default branch. Pull requests only restore, unless you set
save-on-pull-request to let same-repository pull requests save entries of
their own; pull requests from forks never save. See the
GitHub Action guide for complete
workflows, parallel builds, remote caches, and release policy.
Inspect and maintain the cache
mbx doctor # check tools, setup, and cache access
mbx tui # watch builds using this cache
mbx stats # report lifetime savings and workspace sharing
mbx explain --last # explain the last recorded build
mbx cache stats # summarize the store, managed targets, and incremental state
mbx gc --dry-run # preview collection
mbx clean # remove this workspace's managed target
mbx clean --under /tmp/run # remove recorded workspaces beneath a deleted root
mbx adopt --recursive ~/src # adopt existing target directories without deleting outputs
On a filesystem that supports reflinks, restored outputs share data blocks
with the store until modified. Elsewhere, mbx hard links the read-only store
object into place by default. It copies bytes on Windows, when it cannot link,
or with restore_hardlink = false. See
output restoration.
Run mbx adopt to turn existing target/ directories into managed
targets without deleting their contents. A build outside CI does the same
for its own checkout.
Understand managed targets →
Find your next step
Contribute
See CONTRIBUTING.md for development setup, documentation
checks, tests, and pull request conventions. Ask questions in
Discussions; report suspected
vulnerabilities through the private process in SECURITY.md.
mbx builds on Cargo and on ideas from sccache and kache; kache directly
inspired its design. See
Acknowledgements.
License
MIT
