Home Assistant OS VM

Home Assistant OS provides a complete home automation platform with add-ons, supervisor, and automatic updates.

Overview

Home Assistant OS (HAOS) is the recommended installation method for Home Assistant, providing:

Full Supervisor access
Add-ons ecosystem
Automatic updates
Snapshot/backup functionality
Native integration support
Optimized for home automation

Standard Installation

The main HAOS VM script for standard Proxmox VE installations. Script: haos-vm.sh

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/vm/haos-vm.sh)"

Execute the Script

Run the command above from your Proxmox VE shell.

Select Version Channel

Choose between:

Stable (recommended for production)
Beta (test upcoming features)
Dev (bleeding edge, for developers)

Configure VM

Set the following:

VM ID
Hostname
CPU cores (recommended: 2)
RAM (recommended: 4096 MB)
Disk size (recommended: 32 GB)
Network bridge

Wait for Installation

The script downloads the HAOS image and creates the VM.

Access Home Assistant

After the VM starts, access the web interface:

http://homeassistant.local:8123

Or use the VM’s IP address:

http://VM-IP-ADDRESS:8123

Raspberry Pi Installation

Home Assistant OS for Pimox

Special version for Proxmox running on Raspberry Pi (Pimox). Script: pimox-haos-vm.sh

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/vm/pimox-haos-vm.sh)"

This script is specifically designed for Proxmox VE running on Raspberry Pi hardware. Use the standard haos-vm.sh for x86_64 systems.

Version Channels

Stable (Recommended)

Thoroughly tested releases
Production-ready
Recommended for daily use
Regular security updates
Best stability

Beta

Preview upcoming features
Generally stable
Help test before stable release
Minor bugs possible
Good for enthusiasts

Dev (Development)

Latest features
Cutting-edge updates
May have bugs
For developers and testers
Not for production use

Resource Requirements

Minimum Configuration

CPU: 2 cores
RAM: 2 GB (2048 MB)
Disk: 32 GB
Network: 1 Gbps recommended

Recommended Configuration

CPU: 2-4 cores
RAM: 4 GB (4096 MB)
Disk: 32-64 GB
Network: 1 Gbps

Advanced Configuration

CPU: 4+ cores (for many integrations)
RAM: 8 GB (for cameras, media, etc.)
Disk: 64+ GB (for recordings, backups)
Network: 1 Gbps + dedicated VLAN

Home Assistant OS requires at least 32 GB of disk space. The script sets this as the default.

Initial Setup

After the VM is created and started:

Wait for Boot

First boot takes a few minutes as Home Assistant prepares the system.

Access Web Interface

Navigate to http://homeassistant.local:8123 or http://VM-IP:8123

Create Account

Set up your primary user account:

Name
Username
Password
Confirm password

Configure Location

Set your home location for:

Weather information
Sun position
Time zone
Unit system (metric/imperial)

Discover Devices

Home Assistant automatically discovers compatible devices on your network.

Common Integrations

Zigbee

Connect Zigbee devices using Zigbee2MQTT or ZHA add-ons

Z-Wave

Integrate Z-Wave devices with Z-Wave JS add-on

MQTT

Connect IoT devices via Mosquitto MQTT broker

ESPHome

Manage ESP32/ESP8266 devices directly

USB Device Passthrough

For Zigbee/Z-Wave dongles, pass USB devices to the VM:

Identify USB Device

On Proxmox host, list USB devices:

lsusb

Note the device ID (e.g., 10c4:ea60 for Zigbee dongle)

Add USB Device to VM

In Proxmox web UI:

Select the HAOS VM
Go to Hardware
Click Add → USB Device
Select Use USB Vendor/Device ID
Choose your device
Click Add

Restart VM

Restart the Home Assistant VM to detect the USB device.

Configure in Home Assistant

The USB device should now appear in Home Assistant integrations.

# Find USB port
lsusb -t

# In Proxmox, add USB by port (Hardware → Add → USB Device)
# Select "Use USB Port" and choose the correct port

Popular Add-ons

Essential Add-ons

File Editor

Edit configuration files directly from the web interface.Installation: Settings → Add-ons → Add-on Store → File Editor

Mosquitto MQTT Broker

Local MQTT broker for IoT device communication.Installation: Settings → Add-ons → Add-on Store → Mosquitto broker

Terminal & SSH

Command-line access to Home Assistant OS.Installation: Settings → Add-ons → Add-on Store → Terminal & SSH

Samba Share

Advanced Add-ons

Zigbee2MQTT: Alternative Zigbee integration
Node-RED: Visual automation programming
ESPHome: Manage ESP-based devices
AppDaemon: Advanced Python automation
MariaDB: Alternative database backend
InfluxDB: Time-series database for history

Backup and Restore

Create Backup

Navigate to Backups

Settings → System → Backups

Create New Backup

Click Create Backup

Choose Backup Type

Full backup: Everything (recommended)
Partial backup: Select specific components

Download Backup

After creation, download the .tar file to safe location

Restore from Backup

# Upload backup file through Home Assistant UI
# Settings → System → Backups → Upload Backup
# Then click on the backup and select "Restore"

Always keep backups in a separate location from your Proxmox host. Consider automating backups to external storage.

Networking Considerations

Static IP Configuration

Set Static IP

It’s recommended to assign a static IP to Home Assistant:

Via Router: Reserve IP in DHCP settings (recommended)
Via Home Assistant: Settings → System → Network → Configure IPv4

VLAN Configuration

# During VM creation, specify VLAN tag for IoT network isolation
# Or configure after creation in Proxmox:
# VM → Hardware → Network Device → Edit → VLAN Tag

Port Requirements

Port	Protocol	Purpose
8123	TCP	Web Interface
8300	TCP	Home Assistant Supervisor
4357	TCP	Matter
5353	UDP	mDNS (device discovery)
1883	TCP	MQTT (if using Mosquitto)

Troubleshooting

Cannot access homeassistant.local

Use IP address instead: http://VM-IP:8123
Check if mDNS/Avahi is working on your network
Try accessing from same VLAN/subnet
Flush DNS cache on your computer

USB device not detected

Verify USB passthrough in Proxmox VM hardware
Check lsusb output in VM console
Try different USB port on host
Ensure device is not in use by host
Restart VM after adding USB device

VM won't start after update

Check Proxmox logs: journalctl -xe
Verify disk space: pvesm status
Try starting in safe mode via console
Restore from backup if necessary

Slow performance

Increase RAM allocation (4 GB minimum)
Add more CPU cores
Check disk I/O performance
Disable unnecessary integrations
Consider SSD storage for VM disk

Updating Home Assistant

Home Assistant OS automatically checks for updates:

Check for Updates

Settings → System → Updates

Review Release Notes

Click on available update to read release notes

Create Backup

Always backup before updating (Settings → System → Backups)

Install Update

Click Update button and wait for completion

Updates include:

Home Assistant Core
Home Assistant Supervisor
Home Assistant OS
Add-ons

Next Steps

Linux VMs

Deploy Linux virtual machines

Network Appliances

Set up routers and firewalls

VM Overview

Back to all VM scripts

Container Scripts

VM Scripts

Management Tools

Function Libraries

Home Assistant OS VM

Overview

Standard Installation