This guide aims to provide a basic introduction to Mutagen’s design and usage, with links to more advanced topics and features. While it focuses on Mutagen’s low-level primitives, the topics introduced here are a prerequisite for understanding Mutagen’s higher-level orchestration features.
Mutagen is designed and operated around the concept of individual synchronization and forwarding sessions. Each session operates between two endpoints, which in the case of synchronization are file system locations and in the case of forwarding are network endpoints. What makes Mutagen uniquely powerful is that these endpoints can be either local or remote and that sessions can be created with any combination and arrangement of these endpoints.
At a basic level, you can use Mutagen to synchronize source code from your
laptop to a remote cloud server or container in real-time. Or forward requests
localhost:8080 to a web server running inside a container. But Mutagen can
also do things like create a synchronization session between two remote
filesystem using the local system as a proxy. Or perform reverse tunneling from
a container to your laptop. If you have a problem where you need to synchronize
files efficiently or forward network traffic flexibly, then Mutagen can most
likely be used to solve it.
Mutagen can manage any number of concurrent sessions, each of which can be as
ephemeral or permanent as necessary. The
mutagen command itself is designed
entirely around managing session lifecycles. The following sections provide an
outline of the Mutagen session lifecycle by demonstrating their creation,
management, and termination. This guide doesn’t aim to be an exhaustive
exploration of the
mutagen command, and many other options can be discovered
in other parts of the documentation and via the command’s built-in help
$ mutagen --help $ mutagen <command> --help
Before getting into the session management commands, it’s worth mentioning the Mutagen daemon. The daemon is the core of the Mutagen architecture, running in the background as a per-user process, hosting and managing synchronization sessions. While most of the daemon’s lifecycle is automatic, and you don’t need to know anything about it to read this guide, it is important to know about in general. More information can be found in the about the daemon in a later section.
Mutagen provides two sets of session management commands: one for
synchronization sessions (
mutagen sync) and one for forwarding sessions
mutagen forward). They have approximately the same structure, with only a few
minor differences to account for their different purposes.
To create synchronization and forwarding sessions, you use the
mutagen sync create and
mutagen forward create commands, respectively.
Creating a session in Mutagen is as simple as invoking a creation command with
two endpoint URLs, e.g.:
$ mutagen sync create --name=projectCode ~/project email@example.com:~/project
$ mutagen forward create --name=projectTCP tcp:localhost:8080 docker://devcontainer:tcp:localhost:1313
create commands each take two endpoint specifications and create a session
between them. Endpoint specifications can be local,
Docker® containers. For SSH-accessible
endpoints, 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
The exact format for the endpoint specifications and meaning of their order
depends on whether the session is a synchronization or
forwarding session. Both
create commands also take a large
number of configuration options, all of which are documented
in later sections.
Once created, each Mutagen session can be addressed in three different ways: by
name, by label, or by session identifier. Names are optional user-friendly
identifiers that can be specified to the
create commands and used to identify
sessions to other commands. We added names to the sessions that we created above
to make them easier to control. Labels are optional key-value pairs that can be
attached to sessions and queried to perform more complex session selection.
Session identifiers are UUID-based strings that Mutagen generates automatically,
allowing for unambiguous session specification. Session identifiers are printed
out when a session is created and are also available via the
described in the next section. More information about each of these can be found
in the guide on names, labels, and identifiers.
mutagen sync list and
mutagen forward list commands show the current
status of synchronization and forwarding sessions, respectively, e.g.:
$ mutagen sync list Name: projectCode Identifier: ee1a920c-cec2-42b2-a096-dfb7141f83b2 Labels: None Alpha: URL: /home/user/project Connection state: Connected Beta: URL: firstname.lastname@example.org:~/project Connection state: Connected Status: Watching for changes
$ mutagen forward list Name: projectTCP Identifier: 128f8a82-3dd4-4d2b-b0eb-529eee7071da Labels: None Source: URL: tcp:localhost:8080 Connection state: Connected Destination: URL: docker://devcontainer:tcp:localhost:1313 Connection state: Connected Status: Forwarding connections
In the case of synchronization, this output will include any conflicts or
problems that have arisen in the propagation of changes between endpoints. If no
sessions or label selectors are specified to the
list commands, they will
simply print all sessions. More detailed listing output is available through the
Monitoring a session
monitor command shows live monitoring information for a session, e.g.:
$ mutagen sync monitor projectCode Name: projectCode Identifier: ee1a920c-cec2-42b2-a096-dfb7141f83b2 Labels: None Alpha: /home/user/project Beta: email@example.com:~/project Status: Staging files on beta: 75% (8942/11782)
$ mutagen forward monitor projectTCP Name: projectTCP Identifier: 128f8a82-3dd4-4d2b-b0eb-529eee7071da Labels: None Source: tcp:localhost:8080 Destination: docker://devcontainer:tcp:localhost:1313 Status: Forwarding connections: 4 active, 4 total
If no session is specified, the
monitor commands will show information for the
most recently created session of the relevant type.
Synchronization or forwarding can be temporarily halted for a session using the
pause commands, e.g.:
$ mutagen sync pause projectCode
$ mutagen forward pause projectTCP
A session will remain paused until manually resumed.
Sessions can be resumed using the
resume commands, e.g.:
$ mutagen sync resume projectCode
$ mutagen forward resume projectTCP
These commands will ensure that the specified sessions are unpaused and
attempting to synchronize or forward. These commands can also be used to provide
user input (e.g. a password) in cases where the daemon can’t automatically
reconnect to an endpoint in the background because confirmation or
authentication is required. Finally, the
mutagen sync resume command can be
used to resume synchronization when Mutagen’s
safety mechanisms detect a
synchronization anomaly and halt synchronization.
Synchronization cycles can be manually triggered for synchronization sessions
mutagen sync flush command, e.g.:
$ mutagen sync flush projectCode
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 or forwarding can be permanently halted for a session (and the
session deleted) using the
terminate commands, e.g.:
$ mutagen sync terminate projectCode
$ mutagen forward terminate projectTCP
For synchronization sessions, this will not delete files at either endpoint (but should be done before manually deleting files on either endpoint to avoid propagating any deletions).