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 focuseson manual usage, though the topics introduced here are a prerequisite forunderstanding Mutagen’s higher-levelorchestration features.
Design
Mutagen is designed and operated around the concept of individualsynchronization and forwarding sessions. Each session operates between twoendpoints. In the case of synchronization, these endpoints are file systemlocations, and in the case of forwarding, these endpoints are network endpoints.What makes Mutagen uniquely powerful is that sessions can combine any pair ofendpoints, regardless of their location or access mechanism.
Common usage scenarios include synchronizing source code from your laptop to aremote server or container, or forwarding requests from local TCP endpoints toremote web servers. But Mutagen can also do things like synchronize filesbetween two remote filesystems using the local system as a proxy, or performreverse tunneling from a remote system to a service running on your laptop. Ifyou have a problem where you need to synchronize files efficiently or forwardnetwork 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 asephemeral or permanent as necessary. The mutagen command itself is designedentirely around managing session lifecycles. The following sections provide anoutline of the Mutagen session lifecycle by demonstrating their creation,management, and termination. This guide doesn’t aim to be an exhaustiveexploration of the mutagen command, and many other options can be discoveredin other parts of the documentation and via the command’s built-in helpinformation:
# Show general help.mutagen --help# Show help for a specific command.mutagen <command> --helpDaemon
Before getting into the session management commands, it’s worth mentioning theMutagen daemon. The daemon is the core of the Mutagen architecture. It runs inthe background as a per-user process, hosting and managing synchronizationsessions. While most of the daemon’s lifecycle is automatic, and you don’t needto know anything about it to read this guide, it is important to know about ingeneral. More information can be found in the about the daemon in alater section.
Session management
Mutagen provides two sets of session management commands: one forsynchronization sessions (mutagen sync) and one for forwarding sessions(mutagen forward). They have approximately the same structure, with only a fewminor differences to account for their different purposes.
Creating sessions
To create synchronization and forwarding sessions, you use themutagen sync create and mutagen forward create commands, respectively.Creating a session in Mutagen is as simple as invoking a creation command withtwo 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 [emailprotected]:~/projector
# 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:1313The create commands each take two endpoint specifications and create a sessionbetween them. The format for each endpoint specification depends on the desiredtransport. For SSH-accessible endpoints, Mutagenuses OpenSSH under the hood, so all of your settings, keys, and aliases will beautomatically available. For Docker® containers, Mutagen shells outdirectly to the docker command, so DOCKER_HOST and other settings arerespected (and stored) when the session is created. If confirmation orauthentication is required to connect to a remote endpoint, then the createcommand will prompt accordingly.
The exact format for the endpoint specifications and meaning of their orderdepends on whether the session is asynchronization orforwarding session. Both create commands alsotake a large number ofconfiguration options, all of whichare documented in later sections.
Session identification
Once created, each Mutagen session can be addressed in three different ways: byname, by label, or by session identifier. Names are optional user-friendlyidentifiers that can be used to identify sessions to other commands. Labels areoptional key-value pairs that can be attached to sessions and queried to performmore complex session selection. Session identifiers are unique strings thatMutagen generates automatically, allowing for unambiguous session specification.Session identifiers are printed out when a session is created and are alsoavailable via the list commands described in the next section. Moreinformation about each of these can be found in the guide onnames, labels, and identifiers.
Listing sessions
The mutagen sync list and mutagen forward list commands show the currentstatus of synchronization and forwarding sessions, respectively, for example:
$ mutagen sync listName: web-app-codeIdentifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7Labels: NoneAlpha: URL: /home/user/project Connection state: ConnectedBeta: URL: [emailprotected]:~/project Connection state: ConnectedStatus: Watching for changesor
$ mutagen forward listName: web-appIdentifier: fwrd_6mkwS3yuAZyD1VmDtUvCgn3pwqMQf28V4EbxLLvm8OILabels: NoneSource: URL: tcp:localhost:8080 Connection state: ConnectedDestination: URL: docker://devcontainer:tcp:localhost:1313 Connection state: ConnectedStatus: Forwarding connectionsIn the case of synchronization, this output will include any conflicts orproblems that have arisen in the propagation of changes between endpoints. If nosessions or label selectors are specified to the list commands, they willsimply 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, forexample:
$ mutagen sync monitor web-app-codeName: web-app-codeIdentifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7Labels: NoneAlpha: /home/user/projectBeta: [emailprotected]:~/projectStatus: Staging files on beta: 75% (8942/11782)or
$ mutagen forward monitor web-appName: web-appIdentifier: fwrd_6mkwS3yuAZyD1VmDtUvCgn3pwqMQf28V4EbxLLvm8OILabels: NoneSource: tcp:localhost:8080Destination: docker://devcontainer:tcp:localhost:1313Status: Forwarding connections: 4 active, 4 totalIf no session is specified, the monitor commands will show information for themost recently created session of the relevant type.
Pausing sessions
Synchronization or forwarding can be temporarily halted for a session using thepause commands, for example:
# Pause the synchronization session named "web-app-code".mutagen sync pause web-app-codeor
# Pause the forwarding session named "web-app".mutagen forward pause web-appA 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-codeor
# Resume the forwarding session named "web-app".mutagen forward resume web-appThese commands will ensure that the specified sessions are unpaused andattempting to synchronize or forward. They can also be used to provide userinput (for example, a password) in cases where the daemon can’t automaticallyreconnect to an endpoint in the background because confirmation orauthentication is required. Finally, the mutagen sync resume command can beused to resume synchronization when Mutagen’ssafety mechanisms detect asynchronization anomaly and halt synchronization.
Flushing sessions
Synchronization cycles can be manually triggered for synchronization sessionsusing the mutagen sync flush command, for example:
# Flush the synchronization session named "web-app-code".mutagen sync flush web-app-codeThis command will manually trigger a synchronization cycle for the session. Thisis particularly useful when combined with theno-watch filesystem watching mode,allowing users to manually control when synchronization occurs or to integratewith external filesystem watching tools (such asWatchman).
Resetting sessions
Synchronization sessions can have their histories cleared (causing them tobehave like newly created sessions with the same configuration) using themutagen sync reset command, for example:
# Reset the synchronization session named "web-app-code".mutagen sync reset web-app-codeThis command is mostly useful in cases where one ofMutagen’s safety mechanismsengages. It can also be helpful when recreating containerized infrastructurewhere the filesystem isn’t persistent.
Terminating sessions
Synchronization or forwarding can be permanently halted (and the sessiondeleted) using the terminate commands, for example:
# Terminate the synchronization session named "web-app-code".mutagen sync terminate web-app-codeor
# Terminate the forwarding session named "web-app".mutagen forward terminate web-appFor synchronization sessions, this will not delete files at either endpoint (butshould be done before manually deleting files on either endpoint to avoidpropagating any deletions).
