QR Code

Use the QR code displayed at boot to drive the installation

By default Kairos will display a QR code after booting the ISO to install the machine:


The QR Code is a base64 encoded string which is an edgevpn token. For example, you can scan the following QR Code from the video Introduction to Kairos - timestamp 4:16.

The base64 encoded string from the QR Code looks like this:


Once this base64 string is decoded, the edgevpn token looks like this:

    interval: 9223372036854775807
    length: 32
    interval: 9223372036854775807
    length: 32
rendezvous: qfMptAtTsiHqVfVHBaitAmvPdWrJBDpC
mdns: HPtZilIJxPXbQTTHOwdxbXfxKroVbfdH
max_message_size: 20971520

For more information about EdgeVPN, check out the architecture section.

To trigger the installation process via QR code, you need to use the Kairos CLI and provide a Cloud Config, as described in the Getting started guide. You can also see some Cloud Config examples in our Examples section. The CLI is currently available only for Linux and Windows. It can be downloaded from the release artifact:

VERSION=$(wget -q -O- https://api.github.com/repos/kairos-io/provider-kairos/releases/latest | jq -r '.tag_name')
curl -L https://github.com/kairos-io/provider-kairos/releases/download/${VERSION}/kairosctl-${VERSION}-linux-amd64.tar.gz -o - | tar -xvzf - -C .

The CLI allows to register a node with a screenshot, an image, or a token. During pairing, the configuration is sent over, and the node will continue the installation process.

In a terminal window from your desktop/workstation, run:

kairosctl register --reboot --device /dev/sda --config config.yaml
  • The --reboot flag will make the node reboot automatically after the installation is completed.
  • The --device flag determines the specific drive where Kairos will be installed. Replace /dev/sda with your drive. Any existing data will be overwritten, so please be cautious.
  • The --config flag is used to specify the config file used by the installation process.

After a few minutes, the configuration is distributed to the node and the installation starts. At the end of the installation, the system is automatically rebooted.

Last modified February 23, 2024: Reduce sizes and remove warnings (0e183ae)