This guide aims to provide a basic introduction to Mutagen’s design and usage, providing links along the way to more advanced topics and features. It focuses on manual usage, though 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. In the case of synchronization, these endpoints are file system locations, and in the case of forwarding, these endpoints are network endpoints. What makes Mutagen uniquely powerful is that sessions can combine any pair of endpoints, regardless of their location or access mechanism.
Common usage scenarios include synchronizing source code from your laptop to a remote server or container, or forwarding requests from local TCP endpoints to remote web servers. But Mutagen can also do things like synchronize files between two remote filesystems using the local system as a proxy, or perform reverse tunneling from a remote system to a service running on 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
# Show general help. mutagen --help # Show help for a specific command. 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. It runs 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, for example:
# Create a synchronization session named "web-app-code" between the local path # ~/project and an SSH-accessible endpoint. mutagen sync create --name=web-app-code ~/project [email protected]:~/project
# Create a forwarding session named "web-app" between port 8080 on localhost and # port 1313 inside a Docker container. mutagen forward create --name=web-app tcp:localhost:8080 docker://devcontainer:tcp:localhost:1313
create commands each take two endpoint specifications and create a session
between them. The format for each endpoint specification depends on the desired
transport. For SSH-accessible endpoints, Mutagen
uses OpenSSH under the hood, so all of your settings, keys, and aliases will be
automatically available. For Docker® containers, Mutagen shells out
directly to the
docker command, so
DOCKER_HOST and other settings are
respected (and stored) when the session is created. If confirmation or
authentication is required to connect to a remote endpoint, then the
command will prompt accordingly.
The exact format for the endpoint specifications and meaning of their order
depends on whether the session is a
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 used to identify sessions to other commands. Labels are
optional key-value pairs that can be attached to sessions and queried to perform
more complex session selection. Session identifiers are unique 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
list commands 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, for example:
$ mutagen sync list Name: web-app-code Identifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7 Labels: None Alpha: URL: /home/user/project Connection state: Connected Beta: URL: [email protected]:~/project Connection state: Connected Status: Watching for changes
$ mutagen forward list Name: web-app Identifier: fwrd_6mkwS3yuAZyD1VmDtUvCgn3pwqMQf28V4EbxLLvm8OI 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, for
$ mutagen sync monitor web-app-code Name: web-app-code Identifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7 Labels: None Alpha: /home/user/project Beta: [email protected]:~/project Status: Staging files on beta: 75% (8942/11782)
$ mutagen forward monitor web-app Name: web-app Identifier: fwrd_6mkwS3yuAZyD1VmDtUvCgn3pwqMQf28V4EbxLLvm8OI 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, for example:
# Pause the synchronization session named "web-app-code". mutagen sync pause web-app-code
# Pause the forwarding session named "web-app". mutagen forward pause web-app
A session will remain paused until manually resumed.
Sessions can be resumed using the
resume commands, for example:
# Pause the synchronization session named "web-app-code". mutagen sync resume web-app-code
# Resume the forwarding session named "web-app". mutagen forward resume web-app
These commands will ensure that the specified sessions are unpaused and
attempting to synchronize or forward. They can also be used to provide user
input (for example, 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, for example:
# Flush the synchronization session named "web-app-code". mutagen sync flush web-app-code
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 or to integrate
with external filesystem watching tools (such as
Synchronization sessions can have their histories cleared (causing them to
behave like newly created sessions with the same configuration) using the
mutagen sync reset command, for example:
# Reset the synchronization session named "web-app-code". mutagen sync reset web-app-code
This command is mostly useful in cases where one of Mutagen’s safety mechanisms engages. It can also be helpful when recreating containerized infrastructure where the filesystem isn’t persistent.
Synchronization or forwarding can be permanently halted (and the session
deleted) using the
terminate commands, for example:
# Terminate the synchronization session named "web-app-code". mutagen sync terminate web-app-code
# Terminate the forwarding session named "web-app". mutagen forward terminate web-app
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).