mr-boxington README

The project's README from github.com/jdx/mr-boxington. As one markdown file: README.md.

mr boxington

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.

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 Rust option enables wrapping 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

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, older mise versions, and standalone shims.

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 targets 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 command its own target directory to avoid Cargo's directory lock.
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 GitHub Actions cache, a compatible cache server, or an S3-compatible bucket. Pull request builds restore remote work without publishing new objects through mbx.
An explanation for each result. Hits, misses, unavailable lookups, and bypasses are counted separately. mbx explain --last helps diagnose a 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 default backend restores a pruned Cargo target and registry archive; pull requests are restore-only. See the GitHub Action guide for complete workflows, parallel builds, remote servers, and release policy.

Inspect and maintain the cache

mbx doctor          # check tools, setup, and cache access
mbx tui             # watch builds across the machine
mbx stats           # report lifetime savings and workspace sharing
mbx explain --last  # explain the last recorded build
mbx cache stats     # inspect storage
mbx gc --dry-run    # preview collection
mbx clean           # remove this workspace's managed target

On a filesystem that supports reflinks, restored outputs share data blocks with the store until modified. Elsewhere, mbx copies bytes. An existing real target/ is only replaced after you accept a prompt. Understand managed targets →

Find your next step

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

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 was informed by sccache and kache, which directly inspired its design. Acknowledgements.

License

Searching Database…

517 ·GitHub

What is this?

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 only compiles the rest.

Is this a replacement for Cargo or does it sit alongside it?

It sits on top of Cargo rather than replacing it. Each command starts its own cache agent and stops it when the build ends — there is no daemon to manage.

Will every build get a cache hit?

No. A cold store needs a first build to fill it, unsupported invocations simply run without caching, and restored debug info can retain the original checkout's paths.

Does it cache anything besides Rust projects?

Yes, the guides include a standalone mode for C and C++ builds, covering make and CMake.

How do I find out why a build was a miss?

Run mbx explain --last: hits, misses, unavailable lookups and bypasses are counted separately to help you diagnose the build.

What inspired mbx?

It builds on Cargo and was informed by sccache and kache, which the author credits as directly inspiring its design.

Will it touch my existing target/ folder?

An existing real target/ is only replaced after you accept a prompt. On reflink filesystems, restored outputs even share data blocks with the store until modified.

What are similar projects?

kache, buildkit, nx, nub, turborepo, win11-storage-governance-kit, dust, garnet

Which topics is it in?

deduplication, disk-usage, git-worktrees, cache, s3, ci-cd, build-tool, caching, github-actions, cpp, performance, rust

Creator: jdx
Size: 22.2 MB
Stars: 517
Updated: CommitOct 17 Releasev1.24.1Oct 16
Age: 1mo
Commits · 90 Days