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.

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

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 next paragraph for instructions to create an instrumented build.

TPM support

To test the TPM support, you need to install libtpms and swtpm using either instructions from the INSTALL file on their respective GitHub repositories or the AUR packages for Arch Linux users.

Instrumented build for testing

In order to test the QEMU images, you have to select the instrumentation level you want by copying the toolkit/instrumentation.toml.example example in the source tree root folder:

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

The default instrumented configuration will enable you to log in as root without password. You will have to rebuild the project and the QEMU image to apply the change:

(toolkit) $ sujust all
(toolkit) $ sujust qemu