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).
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
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
mutagen daemon stop command.
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
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
mutagen daemon start command, this will avoid starting the daemon process
in the background. The child process can then be terminated directly by the