At the core of Mutagen’s architecture is the Mutagen daemon. The Mutagen daemon is a per-user process that runs in the background, hosting and managing Mutagen’s synchronization and forwarding sessions. All of Mutagen’s session management commands actually dispatch their operations to the daemon and simply output its feedback. Although it’s not a user-facing component, understanding the behavior and lifecycle of the daemon is critical to using Mutagen effectively.


The daemon is designed to operate on a per-user basis. Only a single instance of the daemon is allowed to run for a particular user at any given time. The lifecycle of this instance can be managed in three different ways: automatically, manually, or by the system. All three of these mechanisms can be used in conjunction with one another (e.g. you can manually stop a daemon that was automatically started).

Automatic management

If it’s not already running, the daemon will be started automatically when any session management command is invoked. At system shutdown time, the daemon will terminate gracefully. If you wish to disable automatic daemon startup, you can set the environment variable MUTAGEN_DISABLE_AUTOSTART=1.

Manual management

The daemon can be started manually using the mutagen daemon start command. This command is fast and idempotent, so it can safely be added to your shell initialization script (e.g. .bashrc, etc) if you want the daemon to start automatically when you open a shell. The daemon can also be stopped manually using the mutagen daemon stop command.

System management

If you wish to have the daemon start automatically without any intervention, experimental support for registering the daemon to start automatically on login is available for macOS and Windows via the mutagen daemon register command.


The API that session management commands use to communicate with the daemon isn’t currently stable, so the daemon needs to be restarted when upgrading Mutagen:

$ mutagen daemon stop
$ mutagen daemon start

If you forget, don’t worry, Mutagen will simply print a warning message the next time you try to invoke a session management command.


Experimental support is available for embedding Mutagen and its daemon into other applications. There are two steps to this process: changing the Mutagen data directory to create an isolated daemon instance and (optionally) hosting the daemon process directly.

Mutagen’s data directory stores session configurations, synchronization archives, and more. It’s also the location of the Mutagen daemon IPC endpoint and lock. Its default location is ~/.mutagen, but this can be changed by setting the MUTAGEN_DATA_DIRECTORY environment variable. If specified at daemon startup, this environment variable will tell the daemon to store its data and IPC endpoint in an alternate location. The same environment variable can then be used to tell session management commands where to find that isolated daemon’s IPC endpoint. This variable should be set to an absolute path.

If desired, the daemon can also be hosted by the embedding process by invoking its entry point directly using the hidden mutagen daemon run command. Unlike the mutagen daemon start command, this will avoid starting the daemon process in the background. The child process can then be terminated directly by the hosting process.