Installing HAOS with Armbian Bookworm 12

Nico Writing by Nico
  8 min of reading

This page has been visited ... times

Installing HAOS with Armbian Bookworm 12

It’s almost 2024 and it’s still difficult to install Home Assistant OS on unsupported cards. For the sake of product testing I need to install HAOS on a dedicated card. That’s good, I still have an old Cubietruck card in the boxes so I’ll be able to save money and not invest in a Raspberry pi.

This tutorial will allow you to easily install Home Assistant OS using ARMBIAN and one of the cards supported by this system, all without having an error message in Home Assistant and thus using 100% of the potential of this home assistant .


  • A card supported by Armbian
  • A quality SD card
  • know how to use a terminal
  • know a minimum of the SSH connection

Follow the steps carefully and everything should go well 👌

1st step install Armbian

I’m lucky the Armbian community is still developing an image for the old Cubietruck card, in this case Debian 12 “Bookworm”.

SanDisk Ultra A1 Microsd Memory Card 256GB 128GB 64GB 32GB 16GB microSDHC/SDXC UHS-I U3 V30 TF micro sd card memory card

Sdcard Sandisk

By Sandisk

SanDisk Ultra A1 Microsd Memory Card 256GB 128GB 64GB 32GB 16GB microSDHC/SDXC UHS-I U3 V30 TF micro sd card memory card

Nothing could be simpler go to the dedicated page, download the image and copy it onto a microsd using Rufus or Balena Etcher.

If you also have a cubietruck card and out of curiosity about the hardware you will find information on it on the site Sunxi

Once the image has been copied, insert it and launch the machine, wait around ten minutes before connecting to the system via SSH or via graphical interface if you prefer. Personally, the tutorial is written using a terminal and by ssh.

If you don’t know Armbian, check out the official presentation video:

SSH connection and first launch

You will need to find the IP address of your installation. Throw a little

ssh -p 22 ton-ip -l root

Then the default password for the root user is 1234

For more information on further configuration you can follow the official documentation

Armbian will ask you to:

  • set a new password for the root user
  • choose to install a zsh or bash shell command system at your convenience
  • create a user (optional)
  • create a password for this user
  • to configure a user language system (optional)

Preparing for HAOS

Once restarted, reconnect via ssh and go to the Armbian config


armbian-config user guide

If you have the possibility of installing the system on an emmc type internal memory did it, this is not my case, because the cubietruck uses NAND memory and I would have to put a very very old kernel for it to work.

Armbian-config steps

  1. Firmware update “equivalent update and upgrade” (system > firmware)
  2. Restart
  3. Choice of static or dynamic IP (network > ip)
  4. Bluetooth installation (network > BT install)
  5. configure the wifi connection if necessary (network > wifi)

Preparation for HAos

1 - cgroupv1

exit Armbian in order to be able to configure in cgroupv1. By default Armbian works in cgrouv2 but it turns out that home assistant os runs in cgroupv1 so nothing could be simpler, go to the file armbianEnv.txt

nano /boot/armbianEnv.txt

and paste this code at the bottom of the script, don’t forget to save Ctrl+X et Y


Which will give you an example:


2 - Pretty_Name

Change the name of the distribution so that it is recognized by HAOS

nano /etc/os-release

change PRETTY_NAME=”Armbian 23.02.2 Jammy” by PRETTY_NAME=”Debian GNU/Linux 12 (bookworm)”

don’t forget to save Ctrl+X and Y

Which will give you an example:

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION="12 (bookworm)"
ARMBIAN_PRETTY_NAME="Armbian 23.11.1 bookworm"

find the right architecture

If you don’t know the ARM architecture of your card or if you’re not 100% sure, you can consult these two links below, these are ARM architecture wikis with a complete table.

Architecture arm aarch32 Architecture arm cortex external link

Home Assistant OS installation

Home Assistant has set up an installation tutorial that you can follow to the letter, you just need to choose the right distributions to install in my case the cubietruck is built around an armv7 so I chose:

  • OS-Agent in armv7
  • installing the supervised-installer in qemuarm

supervised-installer installation

Little reminder: armbian is already in root mode by default

1 - install dependencies

apt install \
apparmor \
cifs-utils \
curl \
dbus \
jq \
libglib2.0-bin \
lsb-release \
network-manager \
nfs-common \
systemd-journal-remote \
systemd-resolved \
udisks2 \
wget -y

2 - Reboot system


3 - Install Docker

curl -fsSL | sh

You will get a message that will tell you that you are using docker as a non-root user which will bring up an error message in Home Assistant during the first launch. But don’t worry, you just have to restart Home Assistant and it will correct the situation automatically.

To run Docker as a non-privileged user, consider setting up the
Docker daemon in rootless mode for your user:
WARNING: Access to the remote API on a privileged Docker daemon is equivalent
         to root access on the host. Refer to the 'Docker daemon attack surface'
         documentation for details:

If installing docker on Armbian intrigues you, don’t hesitate to consult the information on the official doc.

4 - Installation OS-Agent

preparing the temporary download file:

mkdir /tmp/download/
chown -Rv _apt:root /tmp/download/
chmod -Rv 700 /tmp/download/
cd /tmp/download/

Download the latest release:


Install there:

dpkg -i os-agent_1.6.0_linux_armv7.deb

Check installation:

gdbus introspect --system --dest io.hass.os --object-path /io/hass/os

You should see a bunch of lines like below:

node /io/hass/os {
  interface org.freedesktop.DBus.Introspectable {
      Introspect(out s out);
      readonly s Version = '1.6.0';
      readwrite b Diagnostics = false;

5 - Install the supervised installer

Last step of the installation, the supervised-installer script will install all the containers necessary for the proper functioning of Home Assistant

wget -O homeassistant-supervised.deb
apt install ./homeassistant-supervised.deb

finally when the script asks you, choose the architecture corresponding to your needs in my case qemuarm.

[info] Install supervisor startup scripts
[info] Install AppArmor scripts
[info] Start Home Assistant Supervised
[info] Installing the 'ha' cli
[warn] Could not find /etc/default/grub or /boot/firmware/cmdline.txt failed to 
switch to cgroup v1
[info] Within a few minutes you will be able to reach Home Assistant at:
[info] http://homeassistant.local:8123 or using the IP address of your
[info] machine: http://ton-ip:8123

Finally patience

Depending on the power of your Home Assistant card it may take more or less time to install so be patient in my case it took around 20 minutes, you can follow the process by going to the address indicated at the end of supervisor script

to not forget

Once you have configured Home Assistant, don’t forget to check for updates and as indicated above you should have a docker error non-root user, don’t panic just restart homeassistant. Personally I restarted the entire system.

non-privileged docker user error

Reboots the entire system from Home Assistant

  • user account > activate advanced mode
  • setting > system > restart home assistant > advanced option > restart system
SanDisk Ultra A1 Microsd Memory Card 256GB 128GB 64GB 32GB 16GB microSDHC/SDXC UHS-I U3 V30 TF micro sd card memory card

Sdcard Sandisk

By Sandisk

SanDisk Ultra A1 Microsd Memory Card 256GB 128GB 64GB 32GB 16GB microSDHC/SDXC UHS-I U3 V30 TF micro sd card memory card


This is an effective way to install Home Assistant OS on Armbian using a compatible card without having to worry. If like me you need to use this magnificent system that is Home Assistant on a recycling card to carry out all types of tests then this tutorial is for you.



Founding member of the Haade site, a home automation enthusiast with all the tricks that go well.