This repository has been archived by the owner. It is now read-only.
Provides a platform to experiment with using Docker to build, distribute and run unikernels.
C Makefile Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Docker unikernel runner for Mirage OS Build status

UPDATE February 2018

Docker unikernel runner was a nice experiment, but I am no longer developing or maintaining this code. This repository is now archived, feel free to fork it.


This is an experimental unikernel runner for running Mirage OS unikernels in Docker containers. Currently the following Mirage OS targets are supported:

  • unix: UNIX userspace using the direct network stack.
  • ukvm: Mirage OS/Solo5 using ukvm as the hypervisor.
  • qemu, kvm (experimental): Mirage OS/Solo5 using software emulation (qemu) or QEMU/KVM (kvm) as the hypervisor.

Quick start with a Mirage application

You will need docker (obviously) and make to drive the top-level build process. The build itself is all run in containers so there are no other host requirements.

  1. Clone this repository, run make. This will build the mir-runner and mir-runner-qemu base images.
  2. Place somewhere in your $PATH.
  3. In the directory containing your built Mirage application, run build HYPERVISOR -t my-unikernel, where HYPERVISOR is one of the supported targets (see note).
  4. Run the unikernel with run --rm -ti my-unikernel.

Note: If you're using Docker for Mac or Docker for Windows, then you will only be able to run images built for the qemu HYPERVISOR locally.

Detailed instructions

This section covers more about how runner works, including how to manually build your own unikernel images without the docker-mirage wrapper script.


To build the runner and all example containers, run:

make tests

See the Makefiles under the tests/ directory for an example of how to manually build unikernel images.

Running the example containers

Use make run-tests to run all tests available on your host. The Mirage/Solo5 tests require KVM and access to /dev/kvm.

Mirage OS/unix

Two containers which build Mirage OS samples from the mirage-skeleton repository are included, mir-stackv4 and mir-static_website.

Each is run as a normal Docker container, however you must pass /dev/net/tun to the container and run with the CAP_NET_ADMIN capability. For example:

docker run -ti --rm \
    --device=/dev/net/tun:/dev/net/tun \
    --cap-add=NET_ADMIN mir-stackv4

CAP_NET_ADMIN and access to /dev/net/tun are required for runner to be able to wire L2 network connectivity from Docker to the unikernel. Runner will drop all capabilities with the exception of CAP_NET_BIND_SERVICE before launching the unikernel.

Mirage OS/Solo5

To run the mir-stackv4 sample using ukvm as a hypervisor:

docker run -ti --rm \
    --device=/dev/kvm:/dev/kvm \
    --device=/dev/net/tun:/dev/net/tun \
    --cap-add=NET_ADMIN mir-stackv4-ukvm

In addition to the requirements for the unix target, access to /dev/kvm is required.

Known issues

  • (#1) Network delays due to random MAC address use. Workaround is: sysctl -w net.ipv4.conf.docker0.arp_accept=1.
  • qemu and kvm support is experimental, currently uses Debian to build the containers due to unknown issues with the Alpine toolchain.