home-assistant-installation-on-debian-14

How to install Home Assistant on Debian 14 “Forky” with QEMU/KVM virtual image

It’s been a tough learning path for me, so I decided to create this tutorial and spare you all that effort.
In this tutorial I will use an old Intel x86 PC as a Home Assistant server.
Please note: in this scenario server is connected with ethernet cable to the LAN router. Wifi has not been tested.

1. Install Debian 14 “Forky”

Download Debian 14 NETINST image and save it on your PC

We’re going to install Debian minimal server, therefore NETINST installer is sufficient for this task. As of may 2026 Debian 14 “Forky” is still in testing phase, so use this URL https://cdimage.debian.org/cdimage/daily-builds/daily/arch-latest/amd64/iso-cd/ to download the debian-testing-amd64-netinst.iso ISO.

As soon as Debian 14 “Forky” becomes stable (expected to happen in 2027), use this URL to download NETINST installer ISO https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/.

Write Debian ISO to USB disk with Rufus

Go to https://rufus.ie/ and download Portable version of this program.

Plug USB disk into your PC and start Rufus. Make sure USB disk is shown in Device section. Select Debian ISO and click Start to write it on the USB disk.

Rufus settings to write Debian ISO on USB disk

Rufus may ask you some questions before writing the image. Just click “OK” / “Confirm” to start the process.

Install Debian on the server machine

Connect your server with RJ45 cable to the LAN router.

Put Debian installer USB disk in USB port.

Turn on the server and enter the BIOS by pressing relevant key on the keyboard. It might be something like DEL, F1, F12 - depends on the manufacturer.

In BIOS make sure that USB disk is selected as a first boot device. Make sure that virtualization is possible and is enabled for your processor.

Save all changes and restart the server. It should now boot from the USB disk and you will see a welcome screen for Debian installer.

Installation is pretty straightfoward. Just follow below video. STOP before GNOME installation (we don’t need that).

After installation is finished remove USB disk and reboot the machine.

Now your Debian 14 server is up and running and can be used in both ways:

host OS on which you will run virtual server with Home Assistant Operating System
general purpose Linux server where you can run any additional services (pihole, file server, whatever)

2. Set up bridge networking on your host OS

By default Debian configures your network interface as a DHCP client, so you get a dynamic IP from your LAN router.
We want to have a static IP on the server, so it can always be connected with the same IP.

Let’s first install bridge-utils package

apt install bridge-utils

Now check your current IP

ip a

Check IP in Debian

In this example we see two network interfaces: lo virtual loopback interface and enp1s0 physical network card connected to LAN router with ethernet cable.
Physical network interface received 192.168.88.16 IP via DHCP.
Now it’s time to plan what static IP we are going to use. It should be outside DHCP IP range. If you don’t know it, safe bet would be to use a high number. In this example I will use 192.168.88.100.

Let’s edit interfaces configuration file

nano /etc/network/interfaces

This is a default view. Your interface name can be different.

Default interfaces in Debian

Let’s define a br0 bridge and bind a physical interface enp1s0 as a bridge port.

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

source /etc/network/interfaces.d/*

# The loopback network interface
auto lo
iface lo inet loopback

# Set up interfaces manually, avoiding conflicts with, e.g., network manager
iface enp1s0 inet manual

# The primary network interface
auto br0
iface br0 inet static
 address 192.168.88.100
 broadcast 192.168.88.255
 netmask 255.255.255.0
 gateway 192.168.88.1
 bridge_ports enp1s0
 bridge_stp off
 bridge_waitport 0
 bridge fd 0

Let’s reboot the server.

systemctl reboot

Check current network status.

ip a

Network bridge in Debian

Bridge br0 is up and static IP is assigned.

3. Install QEMU/KVM and set it up

Home Assistant Operating System (HAOS) can be deployed in couple different ways.
It can be installed standalone on the server, but this way we get a very restriced Linux system without possibility of installing and running additional services.
Therefore in this tutorial HAOS will be run as a virtual server guest in QEMU and our host server (Debian) will provide full functionality of a Linux server for running other services.

Let’s install QEMU and additional packages.

apt install --no-install-recommends qemu-system-x86 libvirt-clients libvirt-daemon-system virt-install ovmf

HAOS virtual image is based on x86 architecture, therefore we are installing only x86 system in order to reduce installation size.

Next step is to setup network in our virtualization system.
We will use virsh for managing guest virtual machines (properly called virtual domains).
Let’s start with following command:

virsh net-list --all

You should see this

QEMU default network

This is a default network. We will modify it. It will be later used by our HAOS virtual machine.
It’s inactive (not started) yet. Let’s make it autostart.

virsh net-autostart default

By default this network uses NAT. We want to change it to bridge.
This way it can use IP address from our LAN range and can be freely accessed within the LAN.

virsh net-edit default

This is a default definition for default network.
UUID is randomly generated. It will be different on your machine.

QEMU default network definition

Let’s change it to:

<network>
  <name>default</name>
  <uuid>PUT-YOUR-UUID-HERE</uuid>
  <forward mode='bridge'/>
  <bridge name='br0'/>
</network>

Now let’s manually start the default network.

virsh net-start default

virsh net-list --all

Start default network in QEMU

We now have a default network set up as a bridge. It will use our host OS bridge.

4. Deploy and run Home Assistant Operating System on QEMU

In this step we need to download HAOS virtual image to our server.

Let’s start with installing necessary packages.

apt install wget xz-utils

Visit https://www.home-assistant.io/installation/linux/ and copy URL to the KVM (.qcow2) image.
Download it with wget to the /var/lib/libvirt/images/ directory.

wget -P /var/lib/libvirt/images/ https://github.com/home-assistant/operating-system/releases/download/17.3/haos_ova-17.3.qcow2.xz

Decompress downloaded file.

unxz /var/lib/libvirt/images/haos_ova-17.3.qcow2.xz

Import HAOS image with virt-install. You might want to change RAM and virtual CPU count as per your need.

virt-install --name haos --description "Home Assistant OS" --os-variant=generic --ram=4096 --vcpus=2 --disk /var/lib/libvirt/images/haos_ova-17.3.qcow2,bus=scsi --controller type=scsi,model=virtio-scsi --import --graphics none --boot uefi

HAOS virtual machine will be started.
Wait until it boots (it might take a while).
Log in with user root and no password.

Home Assistant OS root login

Next step is to configure network in HAOS system.
Let’s first display current network information.

ha network info

Home Assistant default network information

We can see that HAOS default network interface is named enp0s2.
It got a DHCP IP from our LAN router (method: auto).
We want to change it to a static IP (different than the Debian host server).
In my example I’ll make it 192.168.88.101.

ha network update enp0s2 --ipv4-method static --ipv4-address 192.168.88.101/24 --ipv4-gateway 192.168.88.1

Change Home Assistant network to static IP

Optional step:
Change Home Assistant hostname.
By default Home Assistant can be reached with homeassistant hostname.
I want to make it shorter. For instance just ha.

hostnamectl hostname ha

vi /etc/hosts

Change /etc/hosts in Home Assistant

As for now Home Assistant Operating System configuration is finished.
Execute following command:

ha banner

Read and note all important information from the screen.

Home Assistant information

HAOS guest OS can be shut down. We will come back to Debian host OS.

shutdown -h now

We now have Home Assistant virtual machine (virtual domain in QEMU terminology) installed.
In Debian host OS let’s set it up to start automatically on server startup.

virsh autostart haos

Let’s reboot our server and chek if everything works as expected.

shutdown -r now

Wait until Debian server boots up and try to access Home Assistant with it’s URL:
http://ha:8123
or
http://homeassistant:8123
if you decided not to change HAOS hostname.

You should see Home Assistant onboarding screen.

Home Assistant onboarding