You are viewing the development docs which are in progress. For the latest stable documentation, click here.

RaspberryPi

Install Kairos on RaspberryPi

If you are not familiar with the process, it is suggested to follow the quickstart first to see how Kairos works.

Prerequisites

  • An SD card which size is at least 16 GB
  • Etcher or dd
  • A Linux host where to flash the device

Install using AuroraBoot

Create build directory and add cloud-config.yaml, then run:

docker run --rm --privileged -v /var/run/docker.sock:/var/run/docker.sock \
                --platform linux/arm64 -v $PWD/build/:/output \
                kairos.docker.scarf.sh/kairos/auroraboot:latest \
                --debug --set "disable_http_server=true" --set "disable_netboot=true" \
                --set "state_dir=/output" --set "disk.raw=true" \
                --cloud-config /output/cloud-config.yaml \
                --set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-arm64-rpi4-master-k3sv1.32.3-k3s1"

Once complete, use Etcher or dd to flash the image to an SD card:

sudo dd if=build/kairos-@flavor-@flavorRelease-standard-arm64-rpi4-master-k3sv1.32.3+k3s1.raw of=<device> oflag=sync status=progress bs=10MB

Install using images

Download

Extract the img file from a container image as described in this page

Flash the image

Plug the SD card to your system. To flash the image, you can either use Etcher or dd:

sudo dd if=kairos-@flavor-@flavorRelease-standard-arm64-rpi4-master-k3sv1.32.3+k3s1.raw of=<device> oflag=sync status=progress bs=10MB

Once the image is flashed, there is no need to carry out any other installation steps, it can be booted right away. However you may want to add a cloud-config at this point - see below.

Boot

Use the SD Card to boot - the first time will boot into recovery, create COS_STATE and COS_PERSISTENT volumes and reboot, which will take a few minutes depending on the size and speed of the storage. The default username/password is kairos/kairos. To configure your access or disable password change the /oem/90_custom.yaml accordingly.

Configure your node

To configure the device beforehand, be sure to have the SD plugged in your host. We need to overwrite the default configuration file with the desired cloud-config in the COS_OEM partition:

$ OEM=$(blkid -L COS_OEM)
$ mkdir /tmp/oem
$ sudo mount $OEM /tmp/oem
$ sudo cp cloud-config.yaml /tmp/oem/90_custom.yaml
$ sudo umount /tmp/oem

You can push additional cloud config files. For a full reference check out the docs and also configuration after-installation

Last modified May 27, 2025: Update rpi instructions (a475fa3)