Getting started

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.

Design

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 to 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 information:

$ mutagen --help
$ mutagen <command> --help

Daemon

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.

Session management

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.

Creating sessions

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 user@example.org:~/project

or

$ mutagen forward create --name=projectTCP tcp:localhost:8080 docker://devcontainer:tcp:localhost:1313

The create commands each take two endpoint specifications and create a session between them. Endpoint specifications can be local, SSH-accessible, or 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 prompt accordingly.

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.

Session identification

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 list commands described in the next section. More information about each of these can be found in the guide on names, labels, and identifiers.

Listing sessions

The 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: user@example.org:~/project
    Connection state: Connected
Status: Watching for changes

or

$ 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 -l/--long flag.

Monitoring a session

The 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: user@example.org:~/project
Status: Staging files on beta: 75% (8942/11782)

or

$ 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.

Pausing sessions

Synchronization or forwarding can be temporarily halted for a session using the pause commands, e.g.:

$ mutagen sync pause projectCode

or

$ mutagen forward pause projectTCP

A session will remain paused until manually resumed.

Resuming sessions

Sessions can be resumed using the resume commands, e.g.:

$ mutagen sync resume projectCode

or

$ 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.

Flushing sessions

Synchronization cycles can be manually triggered for synchronization sessions using the 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.

Terminating sessions

Synchronization or forwarding can be permanently halted for a session (and the session deleted) using the terminate commands, e.g.:

$ mutagen sync terminate projectCode

or

$ 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).