Install Kairos on RaspberryPi 3 and 4

Kairos supports Raspberry Pi model 3 and 4 with 64bit architecture.

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


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


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. Note it’s compressed with “XZ”, so we need to decompress it first:

xzcat kairos-opensuse-leap-15.5-standard-arm64-rpi4-v3.0.1-k3sv1.29.0-k3s1.img.xz | sudo dd of=<device> oflag=sync status=progress bs=10MB

Once the image is flashed, there is no need to carry any other installation steps. We can boot the image, or apply our config.


Use the SD Card to boot. The default username/password is kairos/kairos. To configure your access or disable password change the /usr/local/cloud-config/01_defaults.yaml accordingly.

Configure your node

To configure the device beforehand, be sure to have the SD plugged in your host. We need to copy a configuration file into cloud-config in the COS_PERSISTENT partition:

$ mkdir /tmp/persistent
$ sudo mount $PERSISTENT /tmp/persistent
$ sudo mkdir /tmp/persistent/cloud-config
$ sudo cp cloud-config.yaml /tmp/persistent/cloud-config
$ sudo umount /tmp/persistent

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

Customizing the disk image

The following shell script shows how to locally rebuild and customize the image with docker

# Download the Kairos image locally
docker pull $IMAGE
# Validate the configuration file
kairosctl validate cloud-config.yaml
# Customize it
mkdir -p build
docker run -v $PWD:/HERE \
 -v /var/run/docker.sock:/var/run/docker.sock \
 --privileged -i --rm \
 --entrypoint=/build-arm-image.sh quay.io/kairos/osbuilder-tools:v0.10.2 \
 --use-lvm \
 --model rpi4 \
 --state-partition-size 6200 \
 --recovery-partition-size 4200 \
 --size 15200 \
 --images-size 2000 \
 --local \
 --config /HERE/cloud-config.yaml \
 --docker-image $IMAGE /HERE/build/out.img

Last modified March 13, 2024: Fix wrong arch and model for rpi docs (951665c)