Running `urunc` on WSL2🔗

In this tutorial, we describe how to set up and run urunc on Windows Subsystem for Linux 2 (WSL2) using QEMU as the underlying hypervisor.

Prerequisites🔗

Before proceeding, make sure you have a working WSL2 instance with Ubuntu installed. You can follow the official Microsoft WSL documentation to set this up.

Verify KVM support🔗

urunc requires KVM for hardware-accelerated virtualization. On WSL2, KVM is available only if nested virtualization is enabled on your Windows host.

Verify that /dev/kvm exists:

ls -la /dev/kvm

If the device is missing, enable nested virtualization by creating or editing the .wslconfig file at %USERPROFILE%\.wslconfig on your Windows host:

[wsl2]
nestedVirtualization=true

Then restart WSL from PowerShell:

wsl --shutdown

After restarting, verify KVM is available:

lsmod | grep kvm

You should see kvm_intel or kvm_amd in the output.

Install `urunc`🔗

Follow the standard installation guide to build and install urunc and the containerd shim.

Snapshotter configuration🔗

The default WSL2 kernel does not load the dm_thin_pool kernel module, which means the devmapper snapshotter will not work out of the box.

Verify this by running:

lsmod | grep dm_thin

If the output is empty, you must use the overlayfs snapshotter instead. This works without any additional configuration on WSL2.

When running containers, use the --snapshotter overlayfs flag:

sudo nerdctl run --snapshotter overlayfs --runtime io.containerd.urunc.v2 ...

Using `nerdctl` instead of Docker🔗

On WSL2, Docker Desktop manages its own containerd instance, which makes it difficult to register custom runtimes like urunc. We recommend using standalone nerdctl with a manually configured containerd instead.

Install nerdctl and the required CNI plugins by following the official nerdctl documentation.

Make sure the CNI plugins (bridge, portmap, etc.) are installed under /opt/cni/bin/.

Running a unikernel🔗

Once everything is set up, you can run a unikernel container. For example, to run the Unikraft nginx image with QEMU:

sudo nerdctl run --rm --snapshotter overlayfs \
  --runtime io.containerd.urunc.v2 \
  harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft:latest

To verify the unikernel is running, check its IP address from the nerdctl output and send a request:

curl http://<unikernel-ip>

You should see the default nginx welcome page.

Running urunc on WSL2🔗