Better shared folders for Virtualbox development boxes

Kennard • June 18, 2019

Chances are that you have had issues while trying to run npm install, gulp watch, npm run dev or something similar on your Homestead, Vagrant or pure Virtualbox machine. This probably had something to do with symlinks not working for your Virtualbox shared folder.

TLDR: Click here to go straight to the installation instructions for Mutagen.

It's a long standing issue that has been discussed many times before, but nobody seems to have a working, reliable solution. It seems that Windows users come across this problem more often than others, but recently I have also had my share of issues while working on a linux host.


This software has provided me with a reliable, working manner of sharing source code with a development box for the first time in years. It provides safe and portable defaults focused specifically on development scenarios. In less than 5 minutes I was up and running and everything just worked®.

The official documentation nicely explains the design philosophy of the application:

Mutagen is designed and operated around the concept of synchronization sessions. A session handles synchronization between an arbitrary pair of endpoints. Each endpoint is just a filesystem location, either local or remote, specified by a URL which Mutagen maps to one of its underlying transports. Mutagen monitors the filesystem contents at each of these locations and triggers a synchronization cycle any time a change is detected. These cycles are fast enough that content synchronizes in effectively real-time. Each cycle uses information about the most recently agreed-upon filesystem contents to identify changes and conflicts between the two endpoints.

Mutagen’s sessions are highly configurable, with various synchronization modes and configurable behavior for ignoring content, permission handling, symbolic link handling, and filesystem watching.

A few important points of attention taken from the documentation:



First download the correct release for your system from the Github releases page. Alternatively install it through homebrew. I assume as the project matures, the application will become available through your average package manager.


Extract the mutagen_<platform>_<arch>_<version>.tar.gz file somewhere and optionally add it to your $PATH. Note that you don't have to extract the contents of the mutagen-agents.tar.gz archive.


Create a global configuration file ~/.mutagen.toml for ease of use. Here is mine. Note that VCS directories such as .git are not synchronized.

vcs = true
default = [
    # System files

    # VIM files

    # IDE specific files


Start the daemon process. You can add this to your .bashrc without any issue. This command is fast and idempotent so don't worry about it being run more than once.

mutagen daemon start

Finally start synchronizing. Make sure you have disabled any other shares or mounts and check that the target directory is empty before you do this. Note that synchronization sessions resume automatically after a reboot if not killed explicitly.

mutagen create /path/to/my/code user@

Optionally monitor the synchronization process

mutagen monitor <session-id>

Depending on the size of your node_modules directory it can take a few seconds to perform the initial synchronization run. After that, changes should be applied near instantly.

Noteworthy mention

During my research I also came across Unison. While this project seems more mature and still pretty active, I opted for Mutagen.