Installing HAOS in a VM on TrueNAS

Install Home Assistant OS

Begin in the TrueNAS UI by adding a new ZVOL at least 32 GiB in size. Note the ZVOL path.

Then, using the TrueNAS shell, run these commands to (1) download, (2) extract, and (3) write the HAOS image for KVM to the ZVOL you created. In the 3rd command, replace tank/vm/haos with the path to your ZVOL. Notice the full ZVOL path should begin with /dev/zvol/ If you are logged in to your TrueNAS as the user root, you should omit sudo from the final command.

wget https://github.com/home-assistant/operating-system/releases/download/15.2/haos_ova-15.2.qcow2.xz
unxz haos_ova-15.2.qcow2.xz
sudo qemu-img convert -p -O raw haos_ova-15.2.qcow2 /dev/zvol/tank/vm/haos

Before moving on, please confirm that your Zvol Volume Size is at least 32 GiB. The Data Written may vary depending on the version of HAOS, but it should be around 586 MiB.

Show Zvol Space Management


Creating a VM on TrueNAS 25.04

Click to Show

:information_source: This section is a work in progress. You may find additional information and screenshots related to the new Instances in this thread, starting here

More information about Instances can be found here

Getting Started

In the TrueNAS UI, select Instances from the left-hand menu. If you have not already done so, click Configuration > Global Settings on the top right of the screen. Check the box to enable, then choose your pool. To keep things simple, this guide assumes that the Instances Default Network uses the default settings.

Show Getting Started

start

Import the ZVOL

Click Configuration > Manage Volumes on the top right of the screen. Next, click Import Zvols. Then select your Zvol and finally click Import.

Show Importing the Zvol

import

Create the Virtual Machine

Click Create New Instance on the top right of the screen.

Instance Configuration
Give your VM a name. Select VM for the Virtualization Method. Under VM Image Options, select “Upload ISO, import a zvol or use another volume”. Then click Select Volume. Finally, select the HAOS volume you imported.

CPU & Memory
Add at least two (2) cores under CPU Configuration and a minimum of 2 GiB for the Memory Size. If needed, these settings can be adjusted at a later time.

Storage
Leave these settings at the defaults. Note: The root disk is not used at this time and is a sparse volume. It will take up an insignificant amount of space.

Network
Uncheck “Use default network settings”. If you have created a bridge on TrueNAS, select the network bridge under Bridged Adapters. If you are not using a bridge, choose your network adapter under Macvlan NICs.

USB Devices
(Optional) USB devices can be added at a later time.

GPU Devices
(Optional) GPU devices can be added at a later time.

PCI Passthrough
(Optional) PCI devices can be added at a later time.

VNC
(Optional) VNC can be enabled at a later time.

Security
You do not need to select anything here.

Click Create

Show Create New Instance

create


More information about creating a VM in TrueNAS 25.04 can be found here

More information about installing HAOS in a VM can be found here

This guide is also posted in the TrueNAS forum and can be found here


Creating a VM on TrueNAS 24.10

Click to Show

Create the Virtual Machine

In the TrueNAS UI, select Virtualization from the left-hand menu, then click the add button to begin the Virtual Machine Creation Wizard.

Step 1 - Set the guest operating system to Linux, give your VM a name, and ensure UEFI is the selected boot method.

Show Operating System

Step 2 - Assign 1 virtual CPU with at least 2 cores and a minimum of 2 GiB memory. Set the CPU mode to host passthrough.

Show CPU and Memory

Step 3 - Click use existing disk image and set the disk type to VirtIO. Select your existing HAOS ZVOL.

Show Disks

Step 4 - Choose a NIC for your VM. Set the adapter type to VirtIO. If you are not using a bridge, enable Trust Guest Filters to allow multicast.

Show Network Interface

Step 5 - Nothing is needed here.

Show Installation Media

Step 6 - Defaults should be fine.

Show GPU

Step 7 - Confirm options and save.

Show Confirm Options


More information about creating a VM in TrueNAS Scale 24.10 can be found here

More information about installing HAOS in a VM can be found here

This guide is also posted in the TrueNAS forum and can be found here


Please see the 2nd post for troubleshooting common issues.

If you prefer running the TrueNAS App for Home Assistant, a setup guide can be found here

49 Likes

Troubleshooting and Additional Information


:warning: Permission denied

The following errors (or similar) when trying to download, extract, or install HAOS using the TrueNAS shell are typically caused by insufficient user permissions.

haos_ova-9.5.qcow2.xz: Permission denied
Cannot write to ‘haos_ova-9.5.qcow2.xz’ (Permission denied).
unxz: haos_ova-9.5.qcow2: Permission denied
qemu-img: /dev/zvol/tank/vm/haos: error while converting raw: Protocol driver 'host_device' does not support image creation, and opening the image failed: Could not open '/dev/zvol/tank/vm/haos': Permission denied

You may need to run the commands as root or use sudo

sudo wget https://github.com/home-assistant/operating-system/releases/download/9.5/haos_ova-9.5.qcow2.xz
sudo unxz haos_ova-9.5.qcow2.xz
sudo qemu-img convert -O raw haos_ova-9.5.qcow2 /dev/zvol/tank/vm/haos

:warning: Cannot grow device files

This can happen when the ZVOL does not get sized correctly.

qemu-img: /dev/zvol/tank/vm/haos: error while converting raw: Cannot grow device files

Confirm the size of your ZVOL is at least 32 GiB


:warning: VM is booting to the UEFI Interactive shell

This happens if we use the incorrect path when writing the HAOS image to our zvol. Notice in the following command that the path starts with /dev/zvol

qemu-img convert -O raw haos_ova-11.5.qcow2 /dev/zvol/tank/vm/haos

If you’re still having trouble, please reply with the exact command you used for this step.


:information_source: Using the ConBee II Zigbee Controller

Unfortunately, the Conbee II is known to not work with USB Passthrough.

You still have a few options, though:

  1. Use PCIe passthrough to connect the USB controller to the VM.
  2. Use this script to start your VM. (this gets old fast)
  3. The final option is to get another Zigbee controller
7 Likes

Happy new year to you.
Will this method use an IP address from the LAN DHCP server, that is, if the IP range is 192.168.0.0/24, will it use an address in it?

Is there USB pass through?

1 Like

Yea, unless you configure something differently the VM will have its own IP in the same network range as your TrueNAS. In Home Assistant, you can configure if it’s a static IP or uses DHCP (default)

Yep - I’m using it with a Gen 5 Z-Stick with the Z-Wave JS UI addon

Here’s how I added it to my VM

And in the addon, I used the /dev/serial/by-id/usb... path that’s typically recommended.

image

2 Likes

Just wanted to chime in that I migrated my HAOS install from ESXi to TrueNAS SCALE successfully by following this guide, including USB passthrough of a Z-Wave/Zigbee coordinator.

Thanks.

I opted for patching the middleware to handle the QEMU Guest Agent, which seems to have worked well as the machine does respond to the shutdown command.

2 Likes

Any particular reason for adding the QEMU Guest Agent?

I’m currently experimenting as I’d like to switch to TrueNAS from RPi4 in a few weeks and not sure why the QEMU Guest Agent is required.

I was able to boot up HA. Do we need it for shutdown, or why?

Edit: I issued Stop and it managed to shutdown.

It’s what the official Home Assistant documentation tells you to do. I’ve tried asking a few times on Discord but never got a reply to precisely what the guest agent does for HAOS.

That was my assumption. If your VM runs and shuts down to your satisfaction, you may skip adding the guest agent. Some other users have not been so lucky.

My VM also shuts down without the guest agent, but I added it anyways because I want everything to work as best as possible.

1 Like

Hello and thank you for the tutorial. I confirm that I also did not need to add the QEMU Guest Agent, the machine starts well when starting truenas scale, and responds to the commands to start and stop the vm.

To understand I directly asked the question to GPT chat “why the QEMU guest agent is necessary for home assistant os?”

And here is his answer: The QEMU guest agent is needed for Home Assistant OS because it allows using virtual devices in a guest OS (like Home Assistant) that does not support them natively. QEMU acts as an emulator that translates virtual device instructions to make them compatible with the guest operating system, so attached devices can be used as if they were connected directly to the host.

Il est possible que vous n’ayez pas besoin de l’agent invitĂ© QEMU si vous n’utilisez pas de pĂ©riphĂ©riques qui nĂ©cessitent une Ă©mulation, ou si vous utilisez un systĂšme d’exploitation qui prend en charge ces pĂ©riphĂ©riques nativement. Cependant, pour certaines personnes, l’utilisation de QEMU peut ĂȘtre nĂ©cessaire pour connecter des pĂ©riphĂ©riques spĂ©cifiques Ă  leur systĂšme Home Assistant, comme des cartes rĂ©seau, des pĂ©riphĂ©riques USB, des disques durs virtuels, etc. Il est donc nĂ©cessaire pour certains utilisateurs pour utiliser certains pĂ©riphĂ©riques qui nĂ©cessite une Ă©mulation pour fonctionner avec Home Assistant OS.

So that was what I originally understood. Normally we do not need Qemu in this specific case of construction

1 Like

I’m having trouble getting USB passthrough working with ConBee II.

I came across this message: VM for Home Assistant OS needs multicast | TrueNAS Community

But it doesn’t seem to work for me. I can confirm that it looks like Scale is grabbing it, because /dev/ttyACM0 exists there

I’m also having issues with the ConBee II USB.

Also, the linked message has a typo. The correct command is:

system advanced update kernel_extra_options="module_blacklist=cp210x"
1 Like

Yeah, I noticed their follow up and fixed the typo. I have an AMD Ryzen if that’s meaningful

up and running had to use sudo with the commands above not sure why but it worked
one problem
my addons are not running
node red
and a few others any advice

Hi, i’m very new to all of this, so excuse my rookie question.
I’m stuck on the first step to dl HAOS
 I’m getting this error when I use the code in the shell:

haos_ova-9.5.qcow2.xz: Permission denied

Cannot write to ‘haos_ova-9.5.qcow2.xz’ (Permission denied).
unxz: haos_ova-9.5.qcow2.xz: No such file or directory
qemu-img: Could not open ‘haos_ova-9.5.qcow2’: Could not open ‘haos_ova-9.5.qcow2’: No such file or directory

Any idea of what I’m doing wrong?

Hi @metatroneoz

Are you logged into the shell as root or another user?

If the first command to dl does not work, none of the remaining commands will work either

Seems like a permissions issue. Try adding sudo to the beginning of each command like this

sudo wget https://github.com/home-assistant/operating-system/releases/download/9.5/haos_ova-9.5.qcow2.xz
sudo unxz haos_ova-9.5.qcow2.xz
sudo qemu-img convert -O raw haos_ova-9.5.qcow2 /dev/zvol/tank/vm/haos

Hi @kzelnick

Sorry I missed your post.

My fault, I need to update the guide to mention that commands may need to be run as root or use sudo. Not every case is the same. It depends on your setup and how you’re accessing the TrueNAS shell.

Were you able to get your add-ons working?

If your still having issues, mind listing all the trouble add-ons. I don’t know how much I can help but I can at least install them to see if I can reproduce the issue.

I did not sure why but a second reboot and they all came up
Works great thanks

Did not do the qemu agent script looked above my paygrade and working without it

Thanks again

Ken

1 Like

I got my SkyConnect and that works for me

1 Like

Hi @troy

Perfect it worked with Sudo. Got HA to run.
I’m having another issue which I can’t seem to figure out. After a few minutes Home assistant loses connection and crashes. I can’t restart it and I have to restart the VM to run it again. There’s no error message that I can see. Would you have any idea why this is happening? (I didn’t set up the qemu agent).

Thank you for your help.

:thinking: I’m not sure @metatroneoz. But I dought this is related to not having the qemu guest agent.

When you’re in TrueNAS, does the DISPLAY button work? Maybe you can find some clues there. For example, is Home Assistant crashing but the supervisor still running, or is it the entire VM that crashes?

From this same page, have you tried downloading the logs?

I’m just making some guesses here. When you log into your TrueNAS UI, are you logging in as root or another user? If it’s another user, try adding them to the root group. I don’t know if it will help, but I’ve seen there is a known issue that has some effect on Apps and VMs when you’re not logged in as root.


I’m sorry I can’t be more helpful - Maybe someone else can jump in with tips for better troubleshooting.

Hi @troy thank you for your help, you are being very kind to try figure out my issues.
So here’s the interesting finding: HA works on the app on my phone (local) all the time, no crashing.
I can’t get to the HA ui in my browser. So there’s nothing wrong from the VM side of things and HA is running stable and fine by the look of it while I’m using the app. I’ve also tested on my laptop and it appears to be working fine there too.
I wonder if it’s an issue with my computer being connected by wifi and some strange local access issue. I don’t know why I can’t access from my iMac. I’ll try some stuff with the cache and other things, hopefully i could fix it.