Installing Nanobox on MacOS High Sierra and Mojave

With the latest releases of MacOS, there have been significant new kernel security measures and a new proprietary file system, Apple File System (APFS). These changes are significant and affect the Nanobox Installation process as well as file system mounting in local environments.

Issues Introduced with High Sierra

There are two main issues introduced with High Sierra that affect the Nanobox installation and configuration processes:

  1. Kernel extensions (KEXTs) now require user approval
  2. APFS doesn't work well with NFS mounts (resolved in 10.13.3+)

Kernel Extensions Require User Approval

As a security measure, Apple now requires explicit user approval before loading 3rd party KEXTs. In local development environments on MacOS, Nanobox builds a private bridge network that needs a TAP driver KEXT. If installing VirtualBox with Nanobox, it requires its own set of KEXTs as well. Once High Sierra detects 3rd party KEXTs being loaded, it will block them until you approve them.


When running in MacOS, Nanobox mounts your local codebase into your local VM either using the native filesystem driver or NFS. Using NFS provides better performance, but with versions of High Sierra before 10.13.3, APFS and NFS don't work well together. Some issues for reference:

NFS folders not properly synced on macOS High Sierra
Vagrant NFS Sync Problem on macOS High Sierra
Homestead NFS Sync on MacOS High Sierra

The issue is resolved in 10.13.3+, but if you're still using an older High Sierra, you can just use the native filesystem driver.

Issues Introduced with Mojave

The major issue introduced with Mojave is that MacOS now requires explicit permission for any app to use the root filesystem. This poses a specific challenge for exporting NFS shares. For more information:

/etc/exports: Operation not permitted

Installing Nanobox

Download and run the Nanobox installer. The first time you run it on High Sierra, it will fail with a message saying system extension(s) were blocked.

Error System Extensions Blocked

When this happens, open your System Preferences panel and go to Security & Privacy. There will be a message at the bottom of this window saying "Some system software was blocked from loading." Click the "Allow" button.

Security & Privacy Preferences

Depending on which Nanobox installer you downloaded (Nanobox standalone vs Nanobox with VirtualBox), there will be one or two extension authors that need to be approved – Mattias Nissler and Oracle America, Inc.

Approve KEXTs

Mattias Nissler is the signed author of the TAP driver required by Nanobox's bridge network. VirtualBox requires a handful of KEXTs signed by Oracle America, Inc.

Once approved, re-run the Nanobox installer.

Note: Some have reported that you can only approve one at a time or that only one will show up. If this is the case, you may have to run the installer again after each approval and come back to approve the next (annoying... I know).

Update Oct 2018: As of MacOS Mojave, the Nanobox will need Full Disk Access in order to mount filesystem via NFS.


First, click "Full Disk Access" on the left, then click "+".


Select "Macintosh HD" in the top dropdown.


Simultaneously press press CMD+shift+. (command-shift-period)

Navigate to '/usr/local/bin/nanobox'

Configure Nanobox

Once Nanobox is installed and you run your first command, it will walk you through a configuration process. One of the questions it will ask is:

Update Jan 2018: As of MacOS High Sierra 10.13.3, the issues between APFS and NFS have been resolved. If you're running 10.13.3+, you can use the netfs option.

Would you like to enable netfs for faster filesystem access (y/n)?

Answer n to use the native filesystem driver rather than NFS.

That should do it! Nanobox will now run on MacOS High Sierra.

Upgrading to High Sierra

If you upgraded to High Sierra after installing Nanobox, you won't have to approve the kernel extensions, but you may still need to switch to the native mount-type. This can be done with the following commands:

# Make sure the Nanobox VM is stopped
nanobox stop

# Switch to the native mount-type
nanobox config set mount-type native

# Start the Nanobox VM
nanobox start

Posted in MacOS, High Sierra