Mutagen is designed to have safe, conservative defaults, focused specifically on development scenarios.

As users integrate Mutagen more deeply into their workflows, they will most likely want to tweak Mutagen’s behavior in one way or another. Configuration parameters are currently available for synchronization modes, ignoring content, permission handling, symbolic link handling, filesystem watching, and file size limits.


Mutagen has four levels of configuration: its own default behavior, the global configuration file (~/.mutagen.toml), per-session configuration, and (for certain behaviors) per-endpoint configuration.

Global configuration takes precendence over default behavior, per-session configuration takes precedence over both, and per-endpoint configurations have the final say. When a session is created, default, global, per-session, and per-endpoint configuration are merged. The merged configuration is “locked in” to the session so that subsequent changes to the ~/.mutagen.toml file will not affect the behavior of existing sessions. This increases safety while removing the cognitive load of having to understand how global configuration changes would propagate.


Mutagen strives to require as little configuration as possible, so its default behavior is designed to be sane, safe, and portable.

Global configuration

The global configuration file allows users to override Mutagen’s default behavior with their own defaults that will apply to all newly created sessions. The file is a TOML file with sections affecting various aspects of Mutagen’s behavior. Existence of the global configuration file is not required.

Per-session configuration

Per-session configuration is provided by flags passed to the create command.

Per-endpoint configuration

Per-endpoint configuration is provided by endpoint-specific flags (i.e. those containing alpha or beta) passed to the create command.