Skip to content

Instantly share code, notes, and snippets.

@coltenkrauter

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

Last active April 8, 2025 16:36
Show Gist options
  • Save coltenkrauter/aee059954b11bf4f6461309af521a277 to your computer and use it in GitHub Desktop.
Save coltenkrauter/aee059954b11bf4f6461309af521a277 to your computer and use it in GitHub Desktop.
Download ZIP
Comprehensive instructions for installing Home Assistant OS in a VM on TrueNAS SCALE.
Raw
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

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

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.

@coltenkrauter
Copy link
Author

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

@ddelella
Copy link

ddelella commented Apr 1, 2025

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.

image

image

@ddelella
Copy link

ddelella commented Apr 8, 2025 •
edited
Loading

@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
Copy link
Author

coltenkrauter commented Apr 8, 2025 •
edited
Loading

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment