Mesa CLI Configuration

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.

Credentials

Variable	Description
`MESA_ACCESS_TOKEN`	Short-lived access token for CLI commands.
`MESA_API_KEY`	API key for CLI commands. Still supported, and it wins if both credential variables are set.

Set MESA_ACCESS_TOKEN to a scoped token you minted on trusted infrastructure, and keep the private key out of the CLI’s environment.

MESA_ACCESS_TOKEN=eyJ... mesa mount --daemonize

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:

mesa mount --daemonize

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.

An existing config file is still honored, searched for in the following locations (highest priority first), or at an explicit --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. Among environment credentials, a matching MESA_ORGS (deprecated) entry takes precedence over MESA_API_KEY, which takes precedence over MESA_ACCESS_TOKEN. Migrate each config key to its environment variable:

Config key	Environment variable
`[organizations.<org>]`	`MESA_ACCESS_TOKEN`
`[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`

Getting Started

Concepts

Reference

MesaFS

Usage Patterns

Integrations

Mesa CLI Configuration

Credentials

Optional

Daemon mode

Ignore rules

Config file (deprecated)

​Credentials

​Optional

​Daemon mode

​Ignore rules

​Config file (deprecated)

Credentials

Optional

Daemon mode

Ignore rules

Config file (deprecated)