Network forwarding

Mutagen v0.10.0+ supports flexible network fowarding, allowing you to connect services and access applications running on different systems. It can be particularly useful when developing applications inside containers that you want to be able to access locally. For example, you might want to develop a web application (potentially with multiple backing services) in a containerized environment but access it from your browser. Network forwarding can also be used to reverse tunnel traffic or forward Unix domain sockets, amongst other things.

Design and architecture

Mutagen’s forwarding sessions each operate between an arbitrary pair of endpoints, termed source and destination, forwarding source’s incoming connections to destination. As with synchronization sessions, remote data is transferred over an agent command’s input/output stream, multiplexed in this case to support multiple connection streams, avoiding the need to expose ports publicly.

Endpoint URLs

Forwarding endpoint URLs are similar to synchronization endpoint URLs, except that, instead of naming a filesystem location, they name a network endpoint. The exact format for forwarding endpoint URLs is transport-dependent, but each contains a <network-endpoint> component which has the following format:


This network endpoint is analagous to the path component of a synchronization URL. For source endpoints, the network endpoint is a listener address on which the endpoint will attempt to bind. For destination endpoints, the network endpoint is a target address that the endpoint will attempt to dial.

The <protocol> and <address> components allow the same values as the network and address arguments (respectively) of Go’s net.Dial and net.Listen functions, except that <protocol> is restricted to tcp, tcp4, tcp6, and unix.

In the case of Unix domain sockets, the address component is a socket path, which can be either relative or absolute. If a relative path is specified, then it will be resolved relative in a manner dependent on the transport being used.


Network forwarding configuration is currently minimal, with configuration options controlling:

Session management

Synchronization sessions are managed using the mutagen forward commands, namely create, list, monitor, pause, resume, and terminate. Example usage for these commands can be found in the Getting started guide. The create command comes with a number of flags that control the configuration of the sessions that it creates, and the other synchronization session management commands all include flags that control their behavior. For more information about a particular command, use:

mutagen forward <command> --help