Environment variables
Every environment variable COMA reads, what it changes and its default.
Settings resolve in this order, later winning: built-in defaults, the config file, environment variables, then flags. coma doctor --json shows the paths COMA resolved.
COMA variables
| Variable | Effect | Default |
|---|---|---|
COMA_HOME | Keeps all of COMA's local files in this directory (see Files) | Per-OS locations |
COMA_CONFIG | Path of the config file. Only the config file moves. --config wins | See Files |
COMA_CONTEXT | The COMA context to use. --context wins | The config file's current context |
COMA_NO_COLOR | Any non-empty value turns colour off, like --no-color | Colour on a terminal |
COMA_NO_INPUT | Any non-empty value forbids prompts, like --no-input | Prompts allowed on a terminal |
COMA_NON_INTERACTIVE | Same as COMA_NO_INPUT | |
COMA_LOG_LEVEL | error, warn, info, debug or trace. --quiet, --verbose, --debug and --trace win | warn |
COMA_LOG_FORMAT | text or json. --log-format wins | text |
COMA_SYNC_ALLOW_BIDIRECTIONAL | 1 or true lets a coma.yaml use bidirectional sync; 0 or false forbids it. Overrides sync.allowBidirectional in the config file | Not allowed |
COMA_SYNC_ENGINE | builtin makes comad sync with COMA's own engine instead of Mutagen | Mutagen, through coma-sync |
COMA_SYNC_HELPER | Path of the coma-sync helper | Next to coma, then ../lib/coma/coma-sync relative to it |
COMA_LOCAL_ENGINES | off stops comad watching local engines for fallback; a colon-separated list of socket paths replaces the default list | Docker Desktop, Podman machine, rootless Podman, Colima, OrbStack, /var/run/docker.sock |
An invalid value for COMA_LOG_LEVEL, COMA_LOG_FORMAT or COMA_SYNC_ALLOW_BIDIRECTIONAL fails the command with invalid_argument (exit 2).
COMA_SYNC_ENGINE, COMA_SYNC_HELPER and COMA_LOCAL_ENGINES are read by comad, which takes its environment from the coma command that starts it. Set them before comad starts, or run coma daemon stop and connect again.
The built-in sync engine never deletes files on the machine, cannot report conflicts and polls for changes. The one-way-mirror and bidirectional sync modes need Mutagen.
Colour and terminals
| Variable | Effect |
|---|---|
NO_COLOR | Any non-empty value turns colour off |
FORCE_COLOR | Any non-empty value forces colour. NO_COLOR and COMA_NO_COLOR win if also set |
TERM | TERM=dumb turns colour off. coma docker and coma podman pass TERM to the machine for interactive commands (default xterm-256color) |
Output that is not a terminal, and all --json output, has no colour.
Standard variables COMA reads
| Variable | Used for |
|---|---|
HOME | Default file locations, ~/.ssh keys and Docker's config directory |
XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_CACHE_HOME, XDG_RUNTIME_DIR | File locations on Linux, when set to absolute paths |
DOCKER_CONFIG | Where COMA writes the coma Docker context, as the Docker CLI does. Default ~/.docker |
SSH_AUTH_SOCK | SSH keys held by ssh-agent |
USER | The SSH user when neither the machine's address nor ~/.ssh/config names one |
SHELL | The default syntax of coma endpoint env |
PATH | Finding docker-compose and credential helpers for coma doctor and coma connect |
coma connect also warns when DOCKER_HOST or DOCKER_CONTEXT is set, and, for a Podman engine, CONTAINER_HOST or CONTAINER_CONNECTION: each overrides the default that connect switches. coma endpoint env prints commands that set them. See Tools that ignore Docker contexts.
Files
| File | COMA_HOME set | macOS | Linux |
|---|---|---|---|
| Config | $COMA_HOME/config.yaml | ~/Library/Application Support/coma/config.yaml | $XDG_CONFIG_HOME/coma/config.yaml |
State database, known_hosts | $COMA_HOME/ | ~/Library/Application Support/coma/ | $XDG_STATE_HOME/coma/ |
| Logs | $COMA_HOME/logs/ | ~/Library/Logs/coma/ | $XDG_STATE_HOME/coma/logs/ |
| Cache | $COMA_HOME/cache/ | ~/Library/Caches/coma/ | $XDG_CACHE_HOME/coma/ |
| Sockets | $COMA_HOME/run/ | ~/.coma/run/ | $XDG_RUNTIME_DIR/coma/ |
On Linux, unset XDG variables fall back to ~/.config, ~/.local/state and ~/.cache, and the socket directory to ~/.coma/run. When the socket directory's path is too long for Unix sockets, COMA uses a short directory under /tmp/coma-<uid>/ instead.
Tests and experiments can use a throwaway home:
COMA_HOME=$(mktemp -d) coma doctor