Mesa CLI Configuration

mesa is configured through environment variables.

Access token

Variable	Description
`MESA_ACCESS_TOKEN`	Short-lived access token for CLI commands.

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 --layout layout.json --daemonize

The CLI derives the organization from the token’s issuer. Use one access token and organization per CLI process.

Variable	Description
`MESA_MOUNT_POINT`	Path where repos are mounted (default: `~/.local/share/mesa/mnt`).
`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`	Daemon log path. Defaults to `/tmp/mesa-<uid>/mesa.log`; falls back to stdout if the file cannot be opened.
`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_SERVICE_DOMAIN`	Custom service domain for self-hosted Mesa.
`MESA_UID` / `MESA_GID`	POSIX owner of the mounted filesystem.

Run mesa mount as a background daemon:

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

Set MESA_MESAIGNORE_PATH to a .mesaignore file to control which files are kept locally vs. uploaded to VCS. See .mesaignore for details.