Comprehensive instructions for installing Home Assistant OS in a VM on TrueNAS SCALE.

detailed-home-assistant-os-installation-in-vm-on-truenas-scale.md

Installing Home Assistant OS in a VM on TrueNAS SCALE

This guide provides detailed steps to install Home Assistant OS (HAOS) in a Virtual Machine (VM) on TrueNAS SCALE.

Table of Contents

• Requirements
• Create a ZVOL
• Setup VM in TrueNAS SCALE
• Install HAOS
• Post-Installation
• Troubleshooting
• Resources
• Collaboration
• Credits

Why Install Home Assistant OS on a VM?

Installing Home Assistant OS on a VM gives you the full package of features, including the Supervisor and Add-ons. Here's why this setup rocks:

1. Add-Ons: You get access to Home Assistant Add-ons, which are like plugins that expand your setup with extra functionalities—think MQTT brokers, databases, or Node-RED.
2. Supervisor: The Supervisor manages your Home Assistant instance, making updates, backups, and system health checks a breeze.
3. Snapshots: VMs make it easy to snapshot your entire setup. Mess something up? Rollback to a previous state in no time.
4. Isolation: Your Home Assistant OS runs in its own VM, separate from other systems, reducing the risk of conflicts.
5. Resource Management: Allocate exactly the resources you need, ensuring Home Assistant runs smoothly without hogging everything else.

For more details, you can check out the Home Assistant OS Installation Guide and the TrueNAS Community Forum.

Requirements

1. TrueNAS SCALE installed.
2. TrueNAS SCALE shell access.

This guide was tested against:

• Version: TrueNAS-SCALE-23.10.2
• Product: TRUENAS-MINI-3.0-X+
• Model: Intel(R) Atom(TM) CPU C3758 @ 2.20GHz
• Memory: 31 GiB

Create a ZVOL

Note: A ZVOL is used instead of a dataset because it allows the storage to be presented as a block device, which is necessary for VM disk images to function correctly.

1. Open TrueNAS SCALE web interface.
2. Navigate to Storage > Pools.
3. Select your pool and click Add Zvol.
4. Set the following:
   • Name: HomeAssistantOS
   • Size: At least 32 GiB
   • Sync: STANDARD
   • Compression Level: Inherit (LZ4)
   • Enable Atime: ON
   • ZFS Deduplication: OFF
   • Case Sensitivity: ON
   • Comments: Home Assistant OS
5. Note the ZVOL path, which will be something like /mnt/your-pool-name/HomeAssistantOS.

Setup VM in TrueNAS SCALE

1. Open TrueNAS SCALE web interface.
   • Navigate to Virtualization > VMs.
   • Click Add to create a new VM.
2. Configure VM settings:
   • Guest Operating System: Linux
   • Name: HAOS
   • Description: Home Assistant OS
   • System Clock: UTC
   • Boot Method: UEFI
   • Shutdown Timeout: 90
   • Start on Boot: Enabled
   • Enable Display: Enabled
   • Bind: 0.0.0.0
   • Password: Set a password for VNC access
3. CPU and Memory:
   • Virtual CPUs: At least 2 vCPUs
   • Cores: 2
   • Threads: 1
   • CPU Mode: Host Passthrough
   • Memory Size: At least 4096 MB
4. Add Storage:
   • Select Disk Type: VIRTIO
   • Use existing disk image: Attach the ZVOL created earlier
5. Configure Network:
   • Adapter Type: VirtIO
   • Mac Address: Auto-generated
   • Attach NIC: Select the network interface used by your system
   • 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.
6. GPU:
   • Hide from MSR: Disabled
   • Ensure Display Device: Enabled
7. Confirm Options and save the VM configuration.

Install HAOS

Note: Here we are just downloading an image and writing it to the disk. The disk in our case is the ZVOL. These steps would be considered the installation. After that, it’s just a matter of adding the ZVOL to a VM and booting up.

1. Download the latest HAOS image using TrueNAS SCALE shell:

   Note that these commands may require admin privilages and per TrueNAS documentation,

   Restrict new TrueNAS user accounts (CORE | SCALE) to the most minimal set of storage ACL permissions and access possible.

   On TrueNAS SCALE, create the administrator account on install and disable root NAS administrative access...

   wget https://github.com/home-assistant/operating-system/releases/download/12.3/haos_ova-12.3.qcow2.xz
   unxz haos_ova-12.3.qcow2.xz
   sudo qemu-img convert -O raw haos_ova-12.3.qcow2 /dev/zvol/path/to/zvol

2. Start the VM.

   • The system should boot directly from the ZVOL and load Home Assistant OS.

Post-Installation

1. Access the HAOS web interface:
   • Open a web browser and navigate to http://<vm-ip>:8123.
2. Complete the initial Home Assistant setup:
   • Set up user account.
   • Configure basic settings.
3. Verify the installation by checking the system information and logs.

Troubleshooting

qemu-img: /dev/zvol/path/to/zvol: error while converting raw: Cannot grow device files

This error occurs when trying to convert the HAOS image to a ZVOL and the ZVOL does not have sufficient space or is incorrectly configured.

Solution:

1. Ensure the ZVOL has enough space.
2. Check the ZVOL path and permissions.
3. Recreate the ZVOL if necessary, ensuring it is at least 32 GiB in size.

VM Stuck in GRUB Loop

If your VM stays in an eternal loop in GRUB, it may indicate a problem with the installation or the image file.

Solution:

1. Ensure the image file is not corrupted.
2. Re-download and extract the image file.
3. Check the ZVOL path and permissions.

USB Passthrough Issues

Issues with USB passthrough can often be resolved by ensuring the correct device path and settings.

Solution:

1. Ensure the USB device is correctly identified and passed through.
2. Use PCIe passthrough for the USB controller rather than USB passthrough per device to avoid issues​:citation[oaicite:2]{index=2}​​:citation[oaicite:1]{index=1}​.

Home Assistant CLI Not Starting

If the Home Assistant CLI is not starting, it may be due to a corrupted download or incorrect setup.

Solution:

1. Delete any existing HAOS files.
2. Re-download and extract the HAOS image.
3. Ensure the ZVOL is correctly configured and has enough space​:citation[oaicite:0]{index=0}​.

Resources

• TrueNAS SCALE Documentation
• Home Assistant OS Installation Guide
• Home Assistant Community Guide
• TrueNAS Community Forum on Installing HAOS
• Josh Creek's Blog on Installing HAOS on TrueNAS SCALE

Collaboration

For contributions, open an issue or pull request in the repository.

Credits

Content based on the Home Assistant Community Guide, Home Assistant OS Installation Guide, and TrueNAS Community Forum.

Authored with assistance from GPT-4, provided by OpenAI.

Thanks for the input @ruifaguiar–I added the following to the above guide based on your feedback.

---

Note that these commands may require admin privilages and per TrueNAS documentation,

> Restrict new TrueNAS user accounts (CORE | SCALE) to the most minimal set of storage ACL permissions and access possible.
> > 
> On TrueNAS SCALE, create the administrator account on install and disable root NAS administrative access...

Honestly thanks for this it’s super helpful! I’m getting lost at finding the IP address of my VM IP so I can login to the OS through a browser, can you tell me where to find it? 😊

I’m getting lost at finding the IP address of my VM IP

If you're having trouble finding the IP address of your VM to log in via a browser, here's a simple way to check:

1. Open the System > Shell in your TrueNAS web interface.
2. Then run the script in this Gist: coltenkrauter/find-all-truenas-vm-ips.sh

These steps do not appear to work for TrueNAS Scale Electric Eel and version 15 of HAOS. Everything completed exactly as described but when I start the VM it sits in the UEFI interactive shell and never boots.

Thanks for letting me know. I am running Electric Eel (though I went through this setup in Dragonfish and later upgraded to Eel).

Here is my HA version (still on 14),

---

I intend to upgrade to version 15 shortly... But, I'll consider running through the entire setup again so see if I am missing anything.

@ddelella Can you share a bit more about your setup? What hardware are you using?

Dell R7425 w/ Dual EPYC 7601
256GB RAM
52TB of usable HDD
NVIDIA Tesla T4

TrueNAS Scale OS (Electric Eel 24.10.2)

I had home assistant running through the Apps section but was having trouble getting my ZBT-1 to be detected through the USB port. I set up the VM to a zvol called HomeAssistantOS as instructed and used the following commands to get the latest stable release:

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

Have you seen any warning or error messages during this process?

No, just the prompt to enter my admin password when using the sudo command.

Looks like this person had the same issue as you — VM boots to UEFI shell instead of starting HAOS.

The root issue is usually that UEFI can’t find the HAOS bootloader. Here’s how to verify that and fix it:

1. Manually boot from the EFI file
   This verifies that the install itself is fine and confirms UEFI can load the OS if pointed correctly.

   At the Shell> prompt, type exit → select Boot Maintenance Manager → Boot From File → pick fs0: → navigate to EFI/BOOT/bootx64.efi and select it to boot.

   If that gets HAOS running, it confirms the image is valid and the issue is just with boot path discovery.
   Supported manual EFI boot method from HAOS docs

2. Copy the bootloader to the UEFI fallback path
   This fixes the boot issue by placing the loader where UEFI expects it by default when no explicit boot entries exist.

   If the manual boot works, SSH into HAOS (or use the terminal add-on) and run:

   mkdir -p /mnt/data/supervisor/boot/EFI/BOOT
   cp /mnt/data/supervisor/boot/EFI/haos/bootx64.efi /mnt/data/supervisor/boot/EFI/BOOT/

   The path EFI/BOOT/bootx64.efi is defined by the UEFI spec as the fallback location when no boot entries are registered. Putting the loader there allows it to boot automatically without shell intervention.

3. Disable Secure Boot
   This avoids silent boot failures due to unsigned bootloaders, which HAOS uses.

   If Secure Boot is enabled in your VM firmware config, disable it. HAOS doesn’t ship with a signed EFI loader, so UEFI will reject it silently under Secure Boot.
   Confirmed workaround in TrueNAS + HAOS thread

4. Adjust the boot order
   This makes sure UEFI tries the disk before the ISO or other devices.

   In TrueNAS VM settings, move the virtual disk above the CD-ROM in the boot priority list. After installation, also consider detaching the ISO — UEFI might still be trying to boot it and falling back to shell when that fails.
   More user reports confirming boot order fixes

---

Disclaimer: I have not performed these steps myself—this was generated using ChatGPT and forum posts

I was able to make it to the "boot from file" but the File Explorer shows nothing. This means the convert command, which I believe it meant to extract the img file, did not work and the zvol is empty.

@coltenkrauter the issue has been resolved. The instructions say to use /dev/zvol/<VolumeName> but that is incorrect. This creates a single file at that location. The actual volume path in Electric Eel needs to be written as /dev/zvol/<PoolName>/<DatasetName>/<VolumeName>. In my case, this turned out to be /dev/zvol/nas/home-assistant/HomeAssistantOS. This extracted and booted up perfectly!

@coltenkrauter the issue has been resolved. The instructions say to use /dev/zvol/<VolumeName> but that is incorrect. This creates a single file at that location. The actual volume path in Electric Eel needs to be written as /dev/zvol/<PoolName>/<DatasetName>/<VolumeName>. In my case, this turned out to be /dev/zvol/nas/home-assistant/HomeAssistantOS. This extracted and booted up perfectly!

Ah, I see. Looks like the instructions say /dev/zvol/<path_to_zvol> which seems correct, but I can see how it might cause confusion.

Thanks for sharing the solution! I'm glad you got it working.

I will go ahead and update /dev/zvol/<path_to_zvol> to be a bit more clear like this, /dev/zvol/path/to/zvol.