OS-level virtualization uses
FUSE to mount Mesa
repositories as real directories on the host. Any tool that works with files —
editors, language servers, build systems, agents — can read and write
repository contents through normal filesystem operations. If you’re not sure
whether you need OS-level or app-level virtualization, see Virtual
Filesystem for an overview and
comparison.
Installation
Install the mesa CLI on macOS or Linux:
curl -fsSL https://mesa.dev/install.sh | sh
General flow
- Install Mesa — install the
mesa CLI and any platform-specific FUSE
dependencies.
- Configure and mount — run
mesa mount (interactive wizard on first run)
or write a config.toml with your API key and run mesa mount --daemonize
for background operation.
- Work with your repos —
cd into the mount path (default:
~/.local/share/mesa/mnt/<org>/<repo>) and use any tool — editors, shell
commands, agents. File changes are automatically persisted back to Mesa.
# Install
curl -fsSL https://mesa.dev/install.sh | sh
# Mount (interactive wizard on first run)
mesa mount --daemonize
# Work with your repos
cd ~/.local/share/mesa/mnt/my-org/my-repo
ls src/
cat README.md
Running inside a sandbox (Docker, Daytona, E2B, etc.)? The same flow applies
— install the CLI, write a config file, and mount. See Working with
Sandboxes for provider-specific
guides. macOS
Mesa requires macFUSE. Follow the official
macFUSE guide to
install it, including:
Linux
Mesa uses FUSE3 via libfuse3. Most full Linux distributions include this by
default and mesa’s installer installs it for you otherwise.
allow_other and user_allow_other
Mesa mounts with the FUSE allow_other option so that other processes — like
your agent, editors, and language servers — can access the mounted filesystem.
Without this, only the process that ran mesa mount would be able to read the
files.
On Linux, this requires user_allow_other to be enabled in /etc/fuse.conf.
Uncomment or add the following line:
If this is not set, mesa mount will fail with a permission error.
If your environment runs as root (common in some CI and container setups),
allow_other works without this setting. But if you’re running as a non-root
user — which is the default in most sandbox providers like Daytona — you’ll
need to ensure this is configured.
Docker
Slim and minimal base images strip out system libraries that Mesa needs at runtime. Install them explicitly:
For Debian-based images like node:22-slim or debian:bookworm-slim:RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates \
fuse3 \
libssl3 \
openssl \
&& rm -rf /var/lib/apt/lists/* \
&& update-ca-certificates
For Alpine-based images like node:22-alpine or alpine:3.21:RUN apk add --no-cache \
ca-certificates \
fuse3 \
openssl
ca-certificates — TLS certificate store, required for connections to Mesa’s API.fuse3 — Userspace FUSE library.openssl (and libssl3 on Debian) — OpenSSL shared library, used for TLS.
If you skip these packages on a slim image, connections to Mesa’s API will fail with errors like gRPC TLS configuration failed: transport error.
Usage
Browsing your repos
Mesa exposes standard filesystem semantics. You can use regular shell commands
— ls, cat, cp, grep, and more — directly against your mounted repos.
cd ~/.local/share/mesa/mnt/my-org
ls
cd my-repo-1
cat README.md
grep -r "TODO" src/
cursor ~/.local/share/mesa/mnt/my-org/my-repo-1
Editing files in repos
Every write you perform in mesa that affects your source code will create a new
automatically in the background. Mesa respects your .gitignore and will not create commits for
files which you have configured as ignored.
Commands
mesa new
Create a new detached from a or ID:
mesa new main
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
New changes are always detached — writes still snapshot the change but do not advance
any bookmark. To work on a bookmark where writes advance it, use mesa edit instead.
mesa edit
Switch to a different bookmark:
The filesystem immediately updates to reflect the selected bookmark. Writes will automatically
advance the bookmark as you work.
You can also resume a previous by ID:
Resuming a change by ID enters detached mode. Any bookmarks that were tracking this change
will still advance automatically as you write.
checkout is an alias for edit: mesa checkout main works identically.
mesa bookmark create
Creates a new pointing at the current :
mesa bookmark create my-feature
-r:
mesa bookmark create my-feature -r main
mesa edit:
mesa bookmark create my-feature
mesa edit my-feature
mesa bookmark list
List all bookmarks for a repository:
mesa log
To look at the log of all your , you can run mesa log. Mesa will
display a list of changes, as well as a helpful diagram.
Workflow examples
Making changes on a feature bookmark
Create a feature bookmark and write some files.
# Start the daemon in the background
mesa mount --daemonize
# Navigate to the mounted repo
cd ~/.local/share/mesa/mnt/my-org/my-repo
# Create a feature bookmark based on the current change and switch to it
mesa bookmark create my-feature
mesa edit my-feature
# Make changes
echo 'export function fix() { return true; }' > src/fix.ts
echo 'import { fix } from "./fix";' >> src/index.ts
mesa edit, the bookmark also advances automatically. There is no manual save step,
changes are persisted to Mesa as you write.
Browsing and switching between bookmarks
Browse a repo, start a feature bookmark, switch between bookmarks, and resume work.
# Start mesa in the foreground
mesa mount
# Navigate to the mounted repo in a separate terminal tab
cd ~/.local/share/mesa/mnt/my-org/my-repo
# Browse the monorepo
ls packages/
cat README.md
grep -r "TODO" src/
# Create a feature bookmark and switch to it
mesa bookmark create my-feature
mesa edit my-feature
# Do some work on the feature bookmark
echo "new feature" > src/new-feature.ts
ls src/
# see the new file new-feature.ts
# Switch back to main
mesa edit main
ls src/
# no new-feature.ts file
# Switch back to the feature bookmark
mesa edit my-feature
ls src/
# see that the new-feature.ts file is back
