Skip to content
TEQcloud Knowledge base

Install Home Assistant OS on your Proxmox Hypervisor

Lab Overview

Section titled “Lab Overview”

This guide documents the installation of Home Assistant OS (HA-OS) on Proxmox, including VM configuration, image import, and static IP assignment. This setup uses a dedicated virtual machine with 2 cores and 4GB RAM (with 2GB ballooning available for expansion). A critical lesson learned addresses static IP configuration, as certain subnet ranges can conflict with Docker’s internal networking.

Setup Steps

Section titled “Setup Steps”

1. Obtain the HA-OS Image

Section titled “1. Obtain the HA-OS Image”
Terminal window
wget <ADDRESS>
  • Extract the compressed QCOW2 image:
Terminal window
unxz /path/to/file.qcow2.xz

Screenshot needed: Proxmox node console showing successful wget download and extraction confirmation.

2. Create the VM in Proxmox

Section titled “2. Create the VM in Proxmox”

Access the Proxmox web interface and create a new VM with the following configuration:

General Tab:

  • Enter a VM name (e.g., “homeassistant”)
  • Set a unique VM ID (e.g., 205)
  • Check “Start at boot” to ensure HA-OS launches when the node restarts

OS Tab:

  • Select “Do not use any media” (we’ll import the image manually)

System Tab:

  • Change “Machine” to q35 for better hardware emulation
  • Change BIOS to OVMF (UEFI) for UEFI boot support
  • Select your EFI storage location (typically local-lvm)
  • Uncheck “Pre-Enroll keys”

Disks Tab:

  • Delete the default SCSI drive and any other pre-created disks

CPU Tab:

  • Set a minimum of 2 cores (single socket)

Memory Tab:

  • Set a minimum of 4096 MB (4GB) with 2GB ballooning enabled for future expansion

Network Tab:

  • Leave default settings unless you have specific requirements (VLAN, static IP, etc.)

Complete the VM creation wizard but do not start the VM yet.

Screenshot needed: VM configuration summary page showing all settings applied.

3. Import the HA-OS Image

Section titled “3. Import the HA-OS Image”

Return to your Proxmox node console and import the downloaded image into the VM:

Terminal window
qm importdisk <VM_ID> /path/to/file.qcow2 <EFI_location>

For example:

Terminal window
qm importdisk 205 /home/user/haos_ova-12.0.qcow2 local-lvm

Wait for the import process to complete.

Screenshot needed: Node console showing successful disk import completion message.

4. Attach the Disk to the VM

Section titled “4. Attach the Disk to the VM”
  • In the Proxmox web interface, select your Home Assistant VM
  • Navigate to the Hardware tab
  • Locate the “Unused Disk” entry and click the Edit button
  • Check the Discard option if using an SSD (improves performance and lifespan)
  • Click Add to attach the disk

Screenshot needed: Hardware tab with newly attached disk visible in the device list.

5. Set Boot Order

Section titled “5. Set Boot Order”
  • In the same VM, navigate to the Options tab
  • Select Boot Order and click Edit
  • Check the newly created drive (typically scsi0)
  • Uncheck all other devices
  • Click OK to save

Screenshot needed: Boot Order configuration showing scsi0 as the only checked device.

6. Start the VM

Section titled “6. Start the VM”
  • Power on the Home Assistant VM
  • Open the VM console to monitor boot
  • After a successful boot, the console will display a message with the Web UI access link (typically in the format homeassistant.local:8123 or <IP>:8123)

Screenshot needed: VM console showing the boot completion message with Web UI URL.

Static IP Configuration

Section titled “Static IP Configuration”

Important Network Consideration

Section titled “Important Network Consideration”

Initially, a static IP of 172.23.30.22/24 was attempted. This configuration caused persistent Web UI connectivity issues across multiple HA-OS versions, suggesting a routing conflict.

Root Cause: Docker (used internally by HA-OS) likely configured a subnet that overlapped with 172.23.30.0/24, creating a routing conflict that prevented Web UI access.

Solution: Changed the static IP to 172.23.30.76/24. This IP assignment resolved the issue completely, and the Web UI became fully accessible.

Recommendation: If you experience Web UI connectivity issues with a static IP configuration, verify that your chosen subnet doesn’t conflict with Docker’s default bridge networks (172.17.0.0/16, 172.18.0.0/16, 172.19.0.0/16, etc.). Consider using IP ranges outside these ranges (e.g., 192.168.x.x or 10.x.x.x).

Accessing Home Assistant

Section titled “Accessing Home Assistant”

After successful boot, access the Web UI at:

http://<HA_VM_IP>:8123

Replace <HA_VM_IP> with the IP address shown in the VM console. If using a static IP, use that address instead.

Screenshot needed: Home Assistant Web UI login page.

Key Specifications

Section titled “Key Specifications”
  • Cores: 2 (single socket)
  • RAM: 4096 MB primary, 2048 MB ballooning
  • Boot Type: UEFI (OVMF)
  • Machine Type: q35
  • Storage: Local LVM
  • Static IP Used: 172.23.30.76/24

Observations and Lessons Learned

Section titled “Observations and Lessons Learned”
  • Manual VM configuration provides better understanding compared to automated scripts.
  • UEFI (OVMF) with q35 machine type offers better compatibility and performance.
  • Disk discard option is beneficial for SSD storage backends.
  • Docker’s internal subnet usage can interfere with static IP configurations—verify your chosen IP range doesn’t conflict with Docker defaults.
  • Ballooning allows flexible RAM allocation without resizing the VM after creation.
  • The HA-OS image handles its own containerization and networking internally; careful IP planning is essential.

References

Section titled “References”