Container Runtimes

The runu OCI runtime enables container managers to run Unikraft unikernels inside lightweight virtual machines as if they were Linux containers.

You can run Unikraft unikernels packaged by KraftKit through any OCI compliant container manager using runu as a drop-in replacement for the runc container runtime, thus enabling the usage of unikernels with familiar container tools and platforms such as Docker and Kubernetes.

Examples of OCI compliant container managers include containerd and cri-o.



The runu OCI runtime must be installed on the Linux host. It enables container managers to run Unikraft unikernels as if they were Linux containers.

runu is open source and distributed under the umbrella of the KraftKit project on GitHub. It can be installed in two different manners, which are detailed below.

Using pre-built binaries#

Select the latest release on the release page for KraftKit, and download the kraftkit_runu tarball for your architecture.

Extract the runu binary from this archive, and install it inside one of the directories listed in the host's PATH variable:

tar -xzvf kraftkit_runu_0.7.0_linux_amd64.tar.gz runu
# PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
sudo install runu /usr/local/bin/

Building from source#

Clone the KraftKit project's Git repository onto the Linux host:

git clone

Then, build the runu binary, and install it inside one of the directories listed in the host's PATH variable:

make runu
# PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
sudo install runu /usr/local/bin/

By default, the build is performed inside a Docker container which has the Go toolchain and other dependencies pre-installed. To disable this behaviour and perform the build on the host instead, simply append the DOCKER= parameter to the make command above.


In this section, we provide examples of running a unikernel that was pre-packaged as an OCI image by KraftKit.

All examples assume as the unikernel image.


Running Unikraft unikernels through Docker using the runu container runtime requires enabling the containerd image store inside the Docker Engine. This feature is currently still considered experimental

Then, running a unikernel is as simple as specifying runu as the container runtime on the command line:

docker run --runtime runu

Docker should display the unikernel in a running state, like any other container:

$ docker ps
1ecef1190a76 "--" Up boring_wozniak


Kubernetes requires alternative container runtimes like runu to be explicitly registered, both in Kubernetes and in the underlying container manager.

Configuring the container manager#

  • If the container manager is containerd, add the following section to the containerd configuration file (default: /etc/containerd/config.toml), and restart the containerd daemon to apply changes:

    runtime_type = "io.containerd.runc.v2"
    BinaryName = "runu"
  • If the container manager is cri-o, create a new configuration file inside the cri-o configuration directory (default: /etc/crio/crio.conf.d/), and restart the crio daemon to apply changes:


Registering a Kubernetes runtime class#

Inside Kubernetes, register runu as a known runtime using a Runtime Class API object. This can be achieved using the kubectl create command with the following manifest:

kind: RuntimeClass
name: runu
handler: runu

Running a unikernel Pod#

The following Pod definition runs a single-container Pod from our unikernel OCI image, using runu as runtime class. It can be created/started using the kubectl create command:

apiVersion: v1
kind: Pod
name: my-unikernel
runtimeClassName: runu
- name: app

Querying the Kubernetes API for running Pods should return the newly created unikernel Pod:

$ kubectl get pods -o wide
my-unikernel 1/1 Running node-1
Edit this page on GitHub

Connect with the community

Feel free to ask questions, report issues, and meet new people.

Join us on Discord!

Getting Started

What is a unikernel?Install CLI companion toolUnikraft InternalsRoadmap

© 2024  The Unikraft Authors. All rights reserved. Documentation distributed under CC BY-NC 4.0.