FAQ

The releases are planned once every 3 months, in general. You can see the planning for the next release on GitHub.

Yes. Unikraft uses a BSD-3 license, which allows use in commercial products.

Unikraft is used by academic institutions and commercial organizations. Check out the full list of adopters in the ADOPTERS.md file.

We are are working towards having Unikraft run baremetal. For more information, check the baremetal-support channel on the Unikraft Discord server. Also see summaries of baremetal discussions.

Initial work on Raspberry Pi support is available in the corresponding repository.

First, join our community server on Discord. Then, send a Pull Request, if you already have an idea of contribution, or ask the community for some contribuition ideas. For more details, see the Contributing section.

Make sure you understand the work that was submitted. If you have questions, ask the author. Make sure the submitted changes follow the coding-style standards. Then follow the Reviewing documentation to approve the Pull Request.

First, ask in the community about the problem you encountered. Most of the time, the issues are common, and known in the community. You can also do some debugging on your own. For details, see the Debugging section.

Unikraft is lightweight and fast, similar to a container, while having the security of a virtual machine. Best of both worlds. For more details, see the Performance and Security sections.

This is caused by missing KVM support. This may be the case if:

• you are running an ARM64 image on x86_64 (or viceversa)
• you are using a virtual machine for development / deployment
• you are using Windows (with WSL) or macOS
• your system simply doesn't have KVM support.

If you are using kraft run, use the -W option to disable KVM support requirement. If you are using QEMU, be sure to not use the -enable-kvm nor the -accel kvm options. Firecracker currently requires KVM support; you can't run it on a KVM-less system.

Use Ctrl+a x (i.e. press Ctrl and a keys simultanously, release, then press x key) to close an open QEMU instance in the terminal. You can also kill all QEMU instances by running, in another console:

pkill -f qemu-system

There's no keyboard shortcut to stop a running Firecracker instance. You either find out the pid and kill it:

pgrep -f firecracker
kill <PID>

Replace <PID> with the actual PID (Process ID) returned by pgrep.

You can also kill all Firecracker instances by running, in another console:

pkill -f firecracker

If you use Ctrl+c that will close the current KraftKit controlling process, but may not fully remove the runtime information, including potential port mappings and potential started QEMU / Firecracker / Xen processes.

Use --rm as argument to kraft run to remove the underlying runtime when using Ctrl+c.

To list all active / inactive KraftKit instances, use:

kraft ps -a

To stop an instance or all instances, or to remove an instance or all instances use:

kraft stop <instance_name>
kraft stop --all
kraft rm <instance_name>
kraft rm --all

There is another instance running that is using port 8080.

First, check the listening services to detect what is using the port:

netstat -tlpn

That may be a KraftKit instance, a QEMU instance, a Firecracker instance, or something else. If it's something else, you can kill it by passing the PID to the kill command:

kill <PID>

If it's a KraftKit, QEMU or Firecracker instance using the port, you can check the running state:

kraft ps -a
ps -ef | grep qemu-system
ps -ef | grep firecracker

You can stop them to free the port:

kraft rm <instance_name>
kill <qemu_PID>
kill <firecracker_PID>

You can also stop all running instances:

kraft rm --all
pkill -f qemu-system
pkill -f firecracker

This is because you passed the debug image (with the .dbg extension) to QEMU. You need to pass the actual image (i.e. without the .dgb extension). The image with the .dbg extension is used by GDB.

See more here.

It's because you don't use KVM support and large pages are required. Pass the -cpu max option to qemu-system-x86_64.

You need to also pass the tag, the full command should be:

kraft run unikraft.org/<app_name>:<tag>

For example, run:

kraft run unikraft.org/nginx:1.25
kraft run unikraft.org/ruby:3.2

If there is an issue with the kraft run commnd, get more info by using the --log-level debug --log-type basic options:

kraft run --log-level debug --log-type basic --rm ...

Note: Place the --log-level debug --log-type basic options immediately after kraft run, as in the command above.

In case of an issue with running QEMU / Firecracker, you should see the generated command line, pointing you to a log file. For example, for QEMU, you will get something like:

qemu-system-x86_64 [...] -serial file:/home/razvand/.local/share/kraftkit/runtime/f93556bb-3cd1-45da-beac-075d1b123a3b/machine.log

The machine.log file may contain useful information related to the runtime issue:

cat /home/razvand/.local/share/kraftkit/runtime/f93556bb-3cd1-45da-beac-075d1b123a3b/machine.log

It's very likely you didn't provide enough memory. Investigate further by using the --log-level debug --log-type basic options to kraft run:

kraft run --log-level debug --log-type basic --rm ...

Use the -M option to kraft run, e.g.:

kraft run --rm -M 256M unikraft.org/ruby:3.2

As above, it's very likely you didn't provide enough memory. Use the -M option to kraft run, e.g.:

kraft run --rm -M 256M unikraft.org/ruby:3.2

The app-... repositories are archived and no longer in use. Visit the catalog repository and see applications and examples there.

Your goal should be to add the appplication to the catalog repository. Follow these guides:

• Using the Application Catalog
• Behind the Scenes with the Application Catalog
• Adding Applications to the Catalog

In its default configuration, KraftKit will start a temporary / transient BuildKit instance.

To speed things up, start a more permanent BuildKit instance that will cache the built filesystems. Follow the instruction here to start a more permanent BuildKit instance.

Use the commands below to clear all KraftKit-related information and then refresh it.

kraft rm --all
kraft pkg rm --all
rm -fr ~/.local/share/kraftkit/
kraft pkg ls --apps --update

Make sure you remove the local configuration and output files beforehand:

rm -f config*
rm -fr .unikraft

There are cached version of repositories. You can clean the KraftKit setup with the steps above:

kraft rm --all
kraft pkg rm --all
rm -fr ~/.local/share/kraftkit/
kraft pkg ls --apps --update

Otherwise, request kraft build to use only fresh images:

kraft build --no-cache --no-update ...