mesa is configured through environment variables. Config files are
deprecated and will stop being read in a future release — see
Config file (deprecated) below for migration.
Required
| Variable | Description |
|---|
MESA_API_KEY | API key for authenticating with Mesa. |
MESA_ORG | Organization name to mount. |
Optional
| Variable | Description |
|---|
MESA_MOUNT_POINT | Path where repos are mounted (default: ~/.local/share/mesa/mnt). |
MESA_REPO_REVS | Per-repo revision pins, comma-separated: org/repo=bookmark:<name> or org/repo=change-id:<hex>. |
MESA_MESAIGNORE_PATH | Path to a global .mesaignore file. See .mesaignore. |
MESA_CACHE_ENABLED | Enable the disk cache (true/false, default: true). |
MESA_CACHE_MAX_SIZE | Maximum disk cache size (e.g. 1GB). |
MESA_CACHE_MAX_MEMORY_SIZE | Maximum in-memory cache size (e.g. 256MB). |
MESA_CACHE_PATH | Path for the disk cache. |
MESA_DAEMON_LOG_FILE | File path for daemon log output (default: stdout). |
MESA_DAEMON_LOG_COLOR | Log color mode: auto, always, or never. |
MESA_PREFETCH_ENABLED | Enable speculative prefetching (true/false). |
MESA_PREFETCH_MAX_DEPTH | Maximum directory depth the prefetcher walks. |
MESA_PREFETCH_MAX_CONCURRENCY | Maximum concurrent prefetch requests. |
MESA_PREFETCH_CACHE_PRESSURE_LIMIT | Fraction of cache budget at which prefetching backs off (0.0–1.0). |
MESA_TELEMETRY | Enable telemetry (true/false). |
MESA_TELEMETRY_COLLECTOR_URL | OpenTelemetry collector URL for trace export. |
MESA_RUNTIME_DIR | Directory for runtime state (PID file, RPC socket). |
MESA_NO_CONFIG_FILE | Skip reading any (deprecated) config file, even at a default search path. Recommended for sandboxes and other hermetic environments. |
MESA_SERVICE_DOMAIN | Custom service domain for self-hosted Mesa. |
MESA_UID / MESA_GID | POSIX owner of the mounted filesystem. |
Daemon mode
Run mesa mount as a background daemon:
Log output goes to stdout by default. Redirect it to a file with
MESA_DAEMON_LOG_FILE:
MESA_DAEMON_LOG_FILE=/var/log/mesa.log mesa mount --daemonize
Ignore rules
Set MESA_MESAIGNORE_PATH to a .mesaignore file to control which files are
kept locally vs. uploaded to VCS. See
.mesaignore for details.
Config file (deprecated)
TOML config files (config.toml and credentials.toml) are deprecated and
will stop being read in a future release. They are never created anymore.
When one is loaded, mesa logs a warning for every setting it contains,
naming the environment variable to use instead.
--config-path:
$XDG_CONFIG_HOME/mesa/config.toml (Linux only)$HOME/.config/mesa/config.toml/etc/mesa/config.toml
Environment variables always take precedence over config file values.
Migrate each config key to its environment variable:
| Config key | Environment variable |
|---|
[organizations.<org>] | MESA_ORG (+ MESA_API_KEY) |
[organizations.<org>] mount = "explicit" | None — explicit mounting is removed; every repo the API key can access is mounted. Scope the key to restrict access. |
[organizations.<org>.repos.<repo>] rev = ... | MESA_REPO_REVS |
mount-point | MESA_MOUNT_POINT |
service-domain | MESA_SERVICE_DOMAIN |
uid / gid | MESA_UID / MESA_GID |
[cache] enabled | MESA_CACHE_ENABLED |
[cache] max-size | MESA_CACHE_MAX_SIZE |
[cache] max-memory-size | MESA_CACHE_MAX_MEMORY_SIZE |
[cache] path | MESA_CACHE_PATH |
[daemon] pid-file | MESA_RUNTIME_DIR (the PID file lives in the runtime directory) |
[daemon.log] target | MESA_DAEMON_LOG_FILE |
[daemon.log] color | MESA_DAEMON_LOG_COLOR |
[telemetry] vendor | MESA_TELEMETRY |
[telemetry] collector-url | MESA_TELEMETRY_COLLECTOR_URL |
[prefetch] * | MESA_PREFETCH_* |
credentials.toml api keys | MESA_API_KEY |
.mesaignore next to config.toml | MESA_MESAIGNORE_PATH |
