A shared cache. A tidier target/.
Reuse Cargo builds across worktrees, keep disk use in check, and run builds together.
Get started · Documentation · Benchmarks · Releases
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.
With mise:
mise use --global --tool-option mr_boxington=true rust mr-boxingtonOr with Cargo:
cargo install mbx --locked
mbx setupWith 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 warningsInteractive 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.
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 →
- 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;
checkandclippyalready 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 --lastdiagnoses 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.
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: jdx/mr-boxington-action@v1
- run: mbx test --workspaceInstall 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.
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 adopt --recursive ~/src # adopt existing target directories without deleting outputsOn 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 →
| Task | Guide |
|---|---|
| Set up editors, watchers, and worktrees | Local development |
| Change budgets or build policy | Configuration |
| Choose mold, Wild, or toolchain LLD | Managed linkers |
| Share work across CI runners | Remote cache |
| Cache make or CMake builds | Standalone C and C++ |
| Investigate an unexpected result | Troubleshooting |
| Look up a command | CLI reference |
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.