Getting started

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.

Design

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

# Show general help.
mutagen --help
# Show help for a specific command.
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. 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.

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, 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

or

# 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

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

Listing sessions

The 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

or

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

Monitoring a session

The monitor command shows live monitoring information for a session, for example:

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

or

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

Pausing sessions

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

or

# Pause the forwarding session named "web-app".
mutagen forward pause web-app

A session will remain paused until manually resumed.

Resuming sessions

Sessions can be resumed using the resume commands, for example:

# Pause the synchronization session named "web-app-code".
mutagen sync resume web-app-code

or

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

Flushing sessions

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

Resetting sessions

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.

Terminating sessions

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

or

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