Mutagen is designed and operated around the concept of synchronization sessions. A session handles synchronization between an arbitrary pair of endpoints.1 Each endpoint is just a filesystem location, either local or remote, specified by a URL which Mutagen maps to one of its underlying transports. Mutagen monitors the filesystem contents at each of these locations and triggers a synchronization cycle any time a change is detected. These cycles are fast enough that content synchronizes in effectively real-time. Each cycle uses information about the most recently agreed-upon filesystem contents to identify changes and conflicts between the two endpoints.
Mutagen can manage any number of concurrent synchronization sessions, and
sessions can be as ephemeral or long-lasting as required. The
is designed entirely around managing session lifecycles. This guide provides an
outline of the Mutagen session lifecycle by demonstrating the creation,
modification, and termination of a Mutagen session.
This guide doesn’t aim to be an exhaustive exploration of the
and many other options can be discovered in other parts of the documentation and
via the command’s built-in help information:
$ mutagen --help $ mutagen <command> --help
Mutagen relies on a daemon that runs in the background as a per-user process and manages synchronization sessions. If a session becomes disconnected from a remote system, the daemon will automatically attempt to reconnect the session in the background.
The Mutagen daemon is started using the daemon command:
$ mutagen daemon start
This command is fast and idempotent, so it can safely be added to your shell
initialization script (e.g.
The daemon will automatically stop at shutdown, but you can also manually stop
mutagen daemon stop. Make sure to stop the daemon before upgrading
Mutagen and to restart it afterwards.
Experimental support for registering the daemon to start automatically on login
is available for macOS and Windows via the
mutagen daemon register command.
Sessions can be created using the create command, e.g.:
$ mutagen create Projects/my_project user@hostname:~/my_project_copy
create command takes two endpoint specifications and creates a
synchronization session between them. The order of the endpoints determines
their identities (the first is referred to as “alpha” and the second as
“beta”) and the synchronization mode specified for the session determines their
roles (for more information, see the
Synchronization modes guide).
Endpoint specifications can be local paths,
SSH-accessible locations, or
Docker® container filesystem locations. They
can refer to individual files or entire directory hierarchies - Mutagen can
handle either. For SSH-accessible locations, Mutagen uses OpenSSH under the
hood, so all of your settings, keys, and aliases will be automatically
available. If confirmation or authentication is required to connect to a remote
endpoint, then the
create command will prompt accordingly.
Mutagen can create synchronization sessions between arbitrary pairs of endpoints — one needn’t be local. For example, you could set up synchronization between an SSH-accessible filesystem location and a Docker container filesystem location without ever having a copy of the files locally. The Mutagen daemon simply acts as a proxy and arbiter for endpoints.
list command shows the current status of sessions, as well as any
conflicts or problems that have arisen in the propagation of changes between
$ mutagen list Session: 7bb4a56b-f4be-4083-be24-7f590beda02e Alpha: URL: /Users/me/Projects/my_project Status: Connected Beta: URL: user@hostname:~/my_project_copy Status: Connected Status: Watching for changes
Each session is assigned a unique identifier that can be used to refer to it in
Mutagen commands. This identifier will be printed by the
create command and
can be seen in the
list command’s output. Sessions can also be referred to (in
list and other commands) by a prefix of this identifier or a fragment of
either endpoint’s path or hostname, so long as this specification is
If no sessions are specified to the
list command, it will simply print all
sessions. More detailed listing output is available through the
monitor command shows live monitoring information for a session:
$ mutagen monitor my_project Session: 7bb4a56b-f4be-4083-be24-7f590beda02e Alpha: /Users/me/Projects/my_project Beta: user@hostname:~/my_project_copy Status: Staging files on beta: 75% (8942/11782)
If no session is specified,
monitor will show information for the most
recently created session.
Synchronization can be temporarily halted for a session using the
$ mutagen pause my_project
A session will remain paused until manually resumed.
Sessions can be resumed using the resume command:
$ mutagen resume my_project
This command will ensure that a session is unpaused and attempting to
synchronize. If the daemon can’t automatically reconnect to an endpoint in the
background because confirmation or authentication is required, the
command can be used to provide the necessary input.
This command is also used to resume synchronization when Mutagen’s safety mechanisms detect a synchronization anomaly.
Synchronization cycles can be manually triggered for sessions using the
$ mutagen flush my_project
This command will manually trigger a synchronization cycle for the session. This
is particularly useful when combined with the
no-watch filesystem watching mode, allowing users to
manually control when synchronization occurs and to integrate with external
filesystem watching tools.
Synchronization can be permanently halted for a session (and the session
deleted) using the
$ mutagen terminate my_project
This will not delete files on either endpoint (but should be done before completely deleting files on either endpoint to avoid propagating any deletions).
1 Although Mutagen only synchronizes directly between two endpoints, multiple synchronization sessions involving a single location can be used to build more complex synchronization topologies, e.g. a star topology with a developer’s local copy at the center.