Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

Mesa is a virtual filesystem that mounts Mesa repositories as local directories without cloning. It is ideal for agents, CI pipelines, and large monorepos where a full clone is impractical. Mesa supports macOS and Linux via FUSE, as well as sandboxless environments via just-bash.
Mesa is early-stage, alpha software. We’ve tried our best to make it reliable, but you may encounter occasional performance/stability issues.If you run into any issues, we urge you to open an issue.

​
How it works

Mesa exposes your Mesa repositories as directories on your local machine. You can read files directly and, when working on a change, create, modify, and delete files — all changes are automatically persisted back to Mesa.

​
Installing

The quickest way to install mesa on macOS or Linux: 
curl -fsSL https://mesa.dev/install.sh | sh
This will auto-detect your platform and install the latest stable release. Re-run the same command at any time to update. For platform-specific FUSE requirements (macFUSE on macOS, user_allow_other on Linux, Docker dependencies), see FUSE.

​
Getting started

The easiest way to get started is to run: 
mesa mount
On your first run, mesa mount will walk you through an interactive configuration wizard and store the config for future use.
The default mount point is ~/.local/share/mesa/mnt on macOS. On Linux, it defaults to $XDG_RUNTIME_DIR/mesa/mnt (typically /run/user/<uid>/mesa/mnt) when available, falling back to ~/.local/share/mesa/mnt.
You need a Mesa account.
Try browsing a repository: 
ls ~/.local/share/mesa/mnt/<your-org>/<your-repo>
When you’re done, hit Ctrl+C and mesa will clean up after itself.
You can control the log level with the MESA_LOG environment variable (uses tracing filter syntax):
MESA_LOG=debug mesa mount

​
Monitoring

Once the daemon is running, you can check its health and performance with: 
mesa stats
This shows cache hit rates, memory and disk usage, network savings, and prefetch progress — useful for tuning your cache configuration or diagnosing performance issues. See the CLI reference for details on each metric. For configuration options, daemon mode, and CLI commands, see the Configuration and Commands reference pages. For commands and workflow examples, see OS-level Virtualization.