Before going further, ensure to get a functional build environment setup

You must complete the toolkit environment setup before executing any command from this page.

Setup and activate the toolkit environment

Setup and activate the CLIP OS toolkit environment in which you will be able to use all the CLIP OS tools required to build and conveniently manage the source tree (such as just to handle the justfile’s and cosmk):

$ toolkit/    # This is to be run at least once on your machine.
$ source toolkit/activate
(toolkit) $           # Your shell prompt is automatically prefixed.

About the CLIP OS toolkit virtualenv setup

The purpose of the script toolkit/ is to compile and store the CLIP OS toolkit environment under the form of a Python virtualenv in run/venv directory. You might be invited to run it again if the specification of the toolkit environment has changed over time.

This setup script can take some time (up to a couple of minutes) to complete on the first launch as it will automatically trigger the compilation of some CPython packages required by the CLIP OS toolkit. Thanks for your patience.

Instrumentation features for testing

Default builds of the project are meant to be set up with a production-ready configuration. There is currently no password-based local login available in this configuration. Thus if you want to test the project in QEMU, you will have to enable some instrumentation features. A good default set of instrumentation features is provided in the toolkit/instrumentation.toml.example example file which can be used as is by copying it to the source tree root folder:

(toolkit) $ cp toolkit/instrumentation.toml.example instrumentation.toml

The default configuration will keep most system configuration unchanged and will give you local password-less root access.


Any change of instrumentation features requires a full project rebuild.

Building the full project

You will then be able to use the justfile’s to run commands to build CLIP OS. Building the CLIP OS project requires multiple successive steps that are described in Justfiles. All commands are run from the project root directory.

To list the available just recipes:

(toolkit) $ just --list

To run all steps required to build CLIP OS:

(toolkit) $ sujust all


As some tasks need root privileges to function properly you must pay attention to which just commands needs root privileges as there are other just commands (such as helpers for source repository and branch manipulation) which do not require root privileges.


On most distributions, the default configuration will reset the PATH environment variable set by the CLIP OS toolkit environment to a fixed default value when calling sudo.

To workaround this issue without modifying your sudoers configuration, the CLIP OS toolkit environment sets an alias for the sudo command to keep your current PATH.


On some distributions (e.g., Debian), the default user $PATH variable does not include the /sbin and /usr/sbin folders. Please add those to your user $PATH. For example:

$ export PATH="$PATH:/sbin:/usr/sbin"

Building a QEMU image and running using QEMU/KVM

TPM emulation support

TPM emulation support is required to test the project under QEMU. To enable it, you may install libtpms and swtpm using either instructions from the INSTALL file on their respective GitHub repositories or the AUR packages for Arch Linux users.

Alternatively, you may enable the initramfs-no-require-tpm instrumentation feature which will allow the initramfs to ask for a passphrase at bootup if TPM support is not available. The default passphrase is core_state_key.

To build a QCOW2 QEMU disk image and to setup a EFI & QEMU/KVM enabled virtual machine with libvirt, use:

(toolkit) $ sujust qemu

Local login disabled by default

The default build configuration will create production images with root access disabled. See the Instrumentation features for testing paragraph for instructions to create an instrumented build.