Skip to main content
Home Assistant is an open-source home automation platform. This guide covers installing Home Assistant OS as a VM on Proxmox VE.

​
Installation Methods

Home Assistant OS runs as a virtual machine (not an LXC container) to provide full access to hardware and ensure compatibility.

Home Assistant OS

Recommended Method
  • Full VM installation
  • Complete Home Assistant features
  • Add-on support
  • Best compatibility

Alternative Methods

Container Options
  • Home Assistant Container
  • Home Assistant Core
  • Limited add-on support

​
Quick Installation

1

Run the Installation Script

Execute the script from your Proxmox shell:
bash -c "$(wget -qO - https://github.com/community-scripts/ProxmoxVE/raw/main/vm/haos-vm.sh)"
2

Choose Installation Type

You’ll be prompted to choose between:
  • Default Settings - Quick setup with recommended values
  • Advanced Settings - Customize all parameters
3

Wait for Installation

The script will:
  • Download the latest Home Assistant OS image
  • Create and configure the VM
  • Import the disk image
  • Configure EFI boot
  • Start the VM (if selected)
4

Access Home Assistant

After the VM boots (2-5 minutes), access Home Assistant at:
http://<vm-ip>:8123

​
Default Configuration

The script uses these default settings:
SettingDefault Value
VM IDNext available ID
Machine Typeq35 (Modern PCIe)
Disk Size32 GB
Hostnamehaos-
CPU ModelKVM64
CPU Cores2
RAM4096 MB (4 GB)
Network Bridgevmbr0
Start VMYes
Home Assistant OS uses UEFI boot with EFI disk and virtio-scsi-pci storage controller for optimal performance.

​
Advanced Configuration

When using advanced settings, you can customize:

​
Version Selection

​
Machine Type

Q35 (Recommended)

Modern machine type with:
  • PCIe support
  • UEFI firmware
  • Better device passthrough
  • Default option

i440fx

Legacy machine type:
  • Older compatibility
  • PCI (not PCIe)
  • Use if migration needed

​
CPU Configuration

Host CPU (Recommended): 
CPU_TYPE="host"
  • Uses host CPU features
  • Better performance
  • Cannot migrate to different CPU types
KVM64 (Compatibility): 
CPU_TYPE="kvm64"
  • Generic CPU model
  • Safe for migration
  • Slightly lower performance

​
Storage Requirements

Minimum: 32 GB (default) Recommended: 64 GB or more for:
  • Multiple integrations
  • Recording history
  • Backups
  • Database growth
Resize disk during installation: 
DISK_SIZE="64G"
Or resize after installation: 
qm resize <VMID> scsi0 +32G

​
Network Configuration

​
Static IP Address

After first boot, configure a static IP:
1

Access Home Assistant

Navigate to http://<vm-ip>:8123
2

Open Network Settings

  1. Complete the initial setup
  2. Go to Settings → System → Network
3

Configure IPv4

Set static IP address, gateway, and DNS servers

​
VLAN Configuration

If you need to assign a VLAN tag: 
# During advanced installation
VLAN="10"  # Your VLAN ID
Or modify after creation: 
qm set <VMID> -net0 virtio,bridge=vmbr0,tag=10

​
Hardware Passthrough

​
USB Device Passthrough

For Zigbee, Z-Wave, or other USB devices:
1

Identify USB Device

lsusb
Note the vendor:product ID (e.g., 10c4:ea60)
2

Add USB Device to VM

qm set <VMID> -usb0 host=10c4:ea60
3

Restart VM

qm stop <VMID>
qm start <VMID>
USB passthrough requires the VM to be stopped before adding devices.

​
GPIO / Serial Devices

For devices requiring serial access: 
# Add serial device
qm set <VMID> -serial0 /dev/ttyUSB0

​
Performance Optimization

​
Enable Ballooning Device

Allow dynamic memory allocation: 
qm set <VMID> -balloon 2048

​
Disk Cache Mode

For better I/O performance: 
qm set <VMID> -scsi0 local-lvm:vm-<VMID>-disk-0,cache=writethrough,discard=on,ssd=1

​
CPU Performance

Pin CPU cores for better performance: 
qm set <VMID> -cores 2 -cpu host,flags=+pcid

​
Backup and Restore

​
Creating Backups

# Create backup with compression
vzdump <VMID> --mode snapshot --compress zstd --storage local

​
Automated Backups

Set up scheduled backups:
  1. Navigate to Datacenter → Backup
  2. Click Add
  3. Configure:
    • Storage location
    • Schedule (e.g., daily at 2 AM)
    • Retention policy
    • Compression method
Recommended Backup Settings:
  • Mode: Snapshot
  • Compression: ZSTD
  • Retention: Keep 7 daily, 4 weekly backups

​
Restore from Backup

# List available backups
ls /var/lib/vz/dump/

# Restore backup
qmrestore /var/lib/vz/dump/vzdump-qemu-<VMID>-*.vma.zst <NEW_VMID>

​
Updating Home Assistant

Home Assistant updates are handled within the OS:
1

Check for Updates

Navigate to Settings → System → Updates in Home Assistant
2

Create Backup

Always backup before updating:
  • Settings → System → Backups → Create Backup
3

Install Update

Click Update and wait for completion (5-15 minutes)
Do NOT update Home Assistant OS from Proxmox. Always use the built-in update mechanism.

​
Troubleshooting

​
VM Won’t Start

qm status <VMID>

qm terminal <VMID>

qm config <VMID> | grep efidisk

​
Can’t Access Web Interface

1

Verify VM is Running

qm status <VMID>
2

Check IP Address

From Proxmox console:
qm guest cmd <VMID> network-get-interfaces
3

Wait for Boot

Home Assistant takes 2-5 minutes to fully boot on first start

​
Disk Space Issues

# Check current disk usage
qm config <VMID> | grep scsi0

# Resize disk
qm resize <VMID> scsi0 +32G
Then resize within Home Assistant:
  1. Settings → System → Storage
  2. Reboot to apply changes

​
Migration from Other Platforms

​
From Raspberry Pi

1

Create Backup on Pi

Create a full backup in Home Assistant
2

Download Backup

Download the .tar backup file
3

Install Fresh HAOS on Proxmox

Use the script to create a new VM
4

Restore Backup

Upload and restore the backup in the new installation

​
From Docker/Supervised

Migrating from Docker or Supervised installations requires careful planning. Some add-ons may not be compatible.
Use the data copy tools: 
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/tools/copy-data/home-assistant-container-copy-data-home-assistant-core.sh)"

​
Best Practices

Regular Backups

  • Daily automated backups
  • Before major updates
  • Before adding integrations
  • Store off-host

Resource Monitoring

  • Monitor CPU usage
  • Watch memory consumption
  • Check disk space
  • Review logs regularly

Security

  • Use strong passwords
  • Enable 2FA
  • Keep HA updated
  • Use HTTPS (reverse proxy)

Network Isolation

  • Separate IoT VLAN
  • Firewall rules
  • No direct internet access
  • Use VPN for remote access

​
Next Steps

Add USB Devices

Configure USB passthrough for Zigbee/Z-Wave

Network Security

Set up VLANs and firewall rules

Reverse Proxy

Install Nginx Proxy Manager for HTTPS

Build docs developers (and LLMs) love

Get started for freeTalk to us