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 configured through a TOML config file. The configuration file is searched for in the following locations
(highest priority first):
$XDG_CONFIG_HOME/mesa/config.toml (Linux only)
$HOME/.config/mesa/config.toml
/etc/mesa/config.toml
You can override the path to the config file with the --config-path flag.
The default configuration file (with all options documented):
# The domain at which all Mesa services are exposed.
#
# You can specify a custom domain, if you are self-hosting Mesa.
service-domain = "mesa.dev"
# The path at which the filesystem should be mounted.
#
# Your organizations will be visible in this path.
mount-point = "/tmp/mesa/mnt"
# The POSIX owning user of the filesystem and all children.
#
# Note that, at this moment, we do not support user names.
uid = 1000
# The POSIX owning group of the filesystem and all children.
#
# Note that, at this moment, we do not support group names.
gid = 1000
# Organizations you are a member of. API tokens live in mesa's secret
# store, not this file — see the "Authentication" reference.
#
# Mount mode controls which repos appear in the FUSE tree:
#
# mount = "all" — mount every repo (default)
# mount = "explicit" — mount only repos listed below
#
# Per-repo overrides:
#
# [organizations.acme-corp.repos.my-repo]
# rev = { bookmark = "main" } # or: rev = { change-id = "abc123..." }
[organizations]
# Disk and in-memory cache configuration.
[cache]
# Enable or disable the disk cache.
#
# NOTE: disabling the disk cache will result in a severe performance hit.
enabled = true
# The path to the cache directory.
#
# Mesa will store its cached data in this directory.
path = "/tmp/mesa/cache"
# Optionally set a maximum bound for the disk cache.
#
# This field supports rich values, so you can specify:
#
# max-size = "10GB'
#
# or
#
# max-size = "100MB"
# max-size =
# Optionally set a maximum bound for the in-memory cache.
#
# This controls how much RAM Mesa uses for caching file contents
# and directory listings. The default is 320 MB.
#
# max-memory-size = "512MB"
#
# or
#
# max-memory-size = "1GB"
# max-memory-size =
# Daemon configuration.
[daemon]
# The path to the PID file for the daemon.
pid-file = "/tmp/mesa/mesa.pid"
# Configuration for the daemon logging.
[daemon.log]
# Where to write log output.
#
# target = { file = "/path/to/your/file" }
# uses the given file path to output logs
#
# target = "stdout"
# writes the log output to stdout
#
# target = "stderr"
# writes the log output to stderr
target = "stdout"
# Enable ANSI color in log output.
#
# color = "auto"
# decides based on whether the output file is a TTY (and `$NO_COLOR`)
#
# color = "always"
# forces the color to be enabled (disrespecting `$NO_COLOR`)
#
# color = "never"
# disables color output
color = "auto"
# Telemetry configuration for exporting OpenTelemetry traces.
[telemetry]
# Whether to send telemetry data to Mesa's servers.
#
# Although our default is to disable this field, we highly encourage you to
# enable vendor telemetry, as that allows us to catch bugs, as well as assist
# you better in case you run into any issues.
vendor = false
# If you wish to add an additional collector for your own internal telemetry,
# add it here.
#
# Example:
#
# collector-url = <https://acme-corp.priv.mesa.dev/v1/traces>
# collector-url =
# Speculative prefetching configuration.
[prefetch]
# Enable or disable speculative prefetching.
#
# When enabled, looking up a directory will trigger background
# fetching of its children's tree listings and blob content.
enabled = true
# Maximum number of concurrent fetch operations.
max-concurrency = 8
# Stop prefetching when blob cache memory usage exceeds this fraction
# of capacity (0.0–1.0).
#
# Prevents deep prefetching from evicting shallow (more valuable)
# entries when the repo is larger than the cache.
cache-pressure-limit = 0.8
# Secret-store configuration.
[secrets]
# Which backend stores API tokens: "encrypted-file" or "plaintext-file".
# Change this via the onboarding wizard or mesa doctor.
backend = "encrypted-file"
Daemon mode
You can run mesa mount as a background daemon:
Daemon logging can be configured in the [daemon.log] section of the config file:
[daemon.log]
# Where to write logs: "stdout", "stderr", or a file path.
target = { file = "/var/log/mesa.log" }
# Color mode: "auto", "always", or "never".
color = "auto"
Ignore rules
Mesa uses a .mesaignore file (alongside config.toml) to control which files are kept locally vs. uploaded
to VCS. See .mesaignore for details.