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 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:
mesa mount --daemonize
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.