Support for Docker® containers

Mutagen has support for synchronizing files and forwarding network traffic in and out of Docker® containers. This support extends to all Docker client platforms (Linux®, macOS, Windows, etc.), Docker daemon setups (local, remote, VM, Hyper-V, etc.), and Docker container types (both Linux and Windows containers are supported).

NOTE: Mutagen assumes that the transport from the docker command to the Docker daemon is secure, and thus Mutagen provides no encryption on top of this transport. For information about securing the Docker daemon, please see the relevant documentation.


Mutagen requires the docker command to be in the user’s path. Due to its use of the -w/--workdir flag with the docker exec command, Mutagen requires a Docker client and daemon supporting API 1.35+. You can check the API version support of your Docker client and daemon by using the docker version command.


Docker container filesystem endpoints can be specified to the mutagen sync create command using URLs of the form:


These URLs support Unicode names and paths and neither require nor support URL escape encoding (i.e. just type “ö”, not “%C3%B6”, etc.).

The <user> component is optional and tells Mutagen to act as the specified user inside the container. If unspecified, Mutagen uses the default container user (usually root for Linux containers or ContainerAdministrator for Windows containers).

The <container> component can specify any type of container identifier understood by docker cp and docker exec, e.g. a name or hexidecimal identifier.

The <path> component must be non-empty (i.e. at least a / character) and can take one of four forms: an absolute path, a home-directory-relative path, a home-directory-relative path for an alternate user, or a Windows absolute path:

# Example absolute path (/var/www)

# Example home-directory-relative path (~/project)

# Example alternate user home-directory-relative path (~otheruser/project)

# Example Windows absolute path (C:\path)

Docker containers must be running to create synchronization sessions and to allow synchronization to run.


Docker container network endpoints can be specified to the mutagen forward create command using URLs of the form:


The <user> and <container> components of this URL are the same those in the synchronization URL format described above, while the <network-endpoint> component is described in the forwarding documentation. In the case of relative Unix domain socket paths, path resolution will be performed relative to the default working directory for the container.

Environment variables

The Docker client’s behavior is controlled by three environment variables:


Mutagen is aware of these environment variables and will lock them in at session creation time (as seen by the mutagen sync create and mutagen forward create commands), including locking in absent or empty values. These locked in values will then be forwarded to any docker commands executed by Mutagen.

If required, endpoint-specific versions of these variables (prefixed with MUTAGEN_ALPHA_/MUTAGEN_BETA_ for synchronization sessions and MUTAGEN_SOURCE_/MUTAGEN_DESTINATION_ for forwarding sessions) can be used to override their values on a per-endpoint basis. This would be necessary to (e.g.) create a synchronization session between two Docker containers hosted on different Docker daemons. In that case, single global values for DOCKER_* environment variables can’t be used (since it would apply to both endpoint URLs), and endpoint-specific variables such as MUTAGEN_ALPHA_DOCKER_HOST or MUTAGEN_BETA_DOCKER_TLS_VERIFY would need to be used when invoking mutagen sync create.

Windows containers

Docker Windows containers are run using Microsoft’s Hyper-V hypervisor, which unfortunately does not allow docker cp operations to copy files into running containers. This means that Mutagen has to stop and restart Windows containers in order to copy its agent executables. Mutagen will prompt the user if this is necessary and allow the user to abort or proceed. If the user decides to proceed, the stop and restart will be automatically performed by Mutagen. This is only necessary if a compatible agent binary doesn’t already exist in the container, so it won’t be necessary on subsequent connection operations.

This restriction does not apply to Linux containers.

Mechanism of action

Mutagen’s support for Docker containers is provided by the Docker client executable on your system. Mutagen uses the docker cp command to copy agent binaries into containers and the docker exec command to run and communicate with the agent binaries over standard input/output streams.

Docker search path

Mutagen uses the first docker executable found in the user’s path (and on macOS includes a few other well-known search paths). This search strategy can be overridden by setting the MUTAGEN_DOCKER_PATH environment variable (for the Mutagen daemon) to a path containing the desired Docker client executable.