I am a true fan of automation. Having a system that automatically responds to external stimuli to achieve a goal is something that astonishes me. I also find this capability of modern systems very useful, and I try to apply it whenever possible. As someone that works closely with computers, I'm somewhat used to automate things, and naturally, this custom leaks into my home. I've been using Home Assistant (which is the de-facto standard for open source automation although there are other competitors that I also used) for some years now, and at first I installed it using the docker container directly into my server. Oh boy, what a mistake. It was unable to work properly due to the close integration that Home Assistant has with the Docker engine directly, so I thought it should be a better way to use Home Assistant.

Home Assistant OS

There is in fact a better way to use Home Assistant, and that is to use the Home Assistant OS. This custom OS contains Home Assistant fully configured to work as smoothly as possible. Naturally, I already had an OS inside my server, so I thought that using a virtual machine to host the Home Assistant OS (HAOS from now on) was the best way. The first choice that should be made is to choose a hypervisor. The most obvious choice in this regard is KVM, the open source module from the Linux kernel. KVM is used through QEMU, a fascinating piece of software that allows to run complete virtual computers and systems as a program inside Linux (I used QEMU once to simulate an STM32F205, and even wrote a patch to add support to one CPU peripheral, but I don't remember if I submitted it to the main repo). But using QEMU directly is somewhat difficult. QEMU CLI accepts a vast number of arguments to configure every aspect of the simulated computer, so usually an intermediate software is used. In my case, I choose incus, since it also is able to manage not only virtual machines, but system containers too (a system container is like a VM but using the same kernel as the host).

Incus

Incus allows the user to create containers and VMs easily, and to achieve that, it manages the resources that are required to configure, manage and launch those virtual systems. It is able to manage storage, networks, images and snapshots among other useful resources used in virtualization. Then, the first thing that should be done to integrate HAOS into Incus is adding the QEMU image into the local Incus image repository. For that, the HAOS QEMU image will be downloaded from here. The image can be downloaded using wget if a terminal is being used:

wget https://github.com/home-assistant/operating-system/releases/download/14.1/haos_ova-14.1.qcow2.xz
unxz haos_ova-14.1.qcow2.xz

Then some metadata should be added to make it possible for Incus to identify and tag that image. A new file called metadata.yaml should be created with this content:

architecture: x86_64
creation_date: 1737803541
properties:
  description: Home Assistant 14.1
  os: HAOS
  release: 20250125

Once the file is created it should be compressed and then we can import the QEMU image while specifying the metadata:

tar -czf metadata.tar.gz metadata.yaml
incus image import metadata.tar.gz haos_ova-14.1.qcow2 --alias haos14.1

Finally, the virtual machine can be created using the following command:

incus launch local:haos14.1 haos-server --vm \
     -c limits.cpu=2 \
     -c limits.memory=2GiB \
     -c boot.autostart=true \
     -c boot.autostart.delay=10 \
     -c security.secureboot=false \
     --device root,size=40GiB

It is important not to forget disabling the secure boot, since Home Assistant OS image is not signed. Failing to configure this flag will make the VM unusable, since it will not launch the OS. Finally, the virtual machine will be created, and it can be accessed using the VM ip, which can be located using the following command:

$ incus ls
+-------------------+---------+--------------------------+------+-----------------+-----------+
|       NAME        |  STATE  |           IPV4           | IPV6 |      TYPE       | SNAPSHOTS |
+-------------------+---------+--------------------------+------+-----------------+-----------+
| homeassistant     | RUNNING | 10.109.215.4 (enp5s0) |      | VIRTUAL-MACHINE | 0         |
|                   |         | 172.30.32.1 (hassio)     |      |                 |           |
|                   |         | 172.30.232.1 (docker0)   |      |                 |           |
+-------------------+---------+--------------------------+------+-----------------+-----------+

This IP is virtual, and it is only accessible from the server, but a reverse proxy can be configured to make it available to the local network. Additionaly, a bridge network can be created in the host server. This allows the virtual machines to have a local IP directly, but the network and the network card should be able to have more than one IP address in one ethernet port. This will be seen in future posts.

Closing

In conclusion, integrating Home Assistant OS with Incus made managing home automation setup easier and more reliable, since my other pieces of software stopped interfering with the Home Assistant system. With the bridge network the Home Assistant is able to detect broadcasted systems and it works flawlessly. Stay tuned for more updates on my infrastructure adventures!

Acknowledgements

Header image: By Hussein Kefel - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=30774773