Install Home Assistant OS HAOS Proxmox VM Guide

This guide covers how to install Home Assistant OS HAOS Proxmox VM using the community helper script. Every time you ask Google Home to dim your lights, that command travels to a server in the United States, gets processed, and comes back. Your occupancy patterns, temperature schedules, and motion sensor data leave your home continuously. For EU residents, this creates a direct conflict with GDPR principles around data minimization and storage location. With Home Assistant OS running locally on Proxmox, zero sensor data leaves your network. Your smart home also stays fully functional during internet outages. This is the only setup we recommend at SelfHostHero.

What Data Leaves Your Home With Cloud Smart Home Platforms

• Voice commands and their timestamps
• Motion sensor trigger patterns (which rooms, at what times)
• Temperature and humidity readings
• Occupancy schedules derived from sensor activity
• Device state changes (lights on/off, locks engaged)

All of this travels to third-party servers, primarily in the United States, under the data policies of Google, Amazon, or Apple.

What This Guide Covers (And What It Does Not)

This guide covers one specific installation method: Home Assistant OS (HAOS) running as a full virtual machine inside Proxmox VE, using the community helper script. We are not covering Home Assistant Container, Home Assistant Core, or bare-metal installs on a Raspberry Pi.

A common question on Reddit is: “Do I even need the helper script?” The answer is yes. The helper script installs HAOS, which includes the Supervisor. The Supervisor is the management layer that powers the Add-on Store. Without the Supervisor, you cannot install one-click add-ons like Zigbee2MQTT, ESPHome, or the NGINX proxy manager. You would have to manage every integration as a separate, manually updated service. The helper script is not a shortcut. It is the correct installation path.

Prerequisites and Minimal Hardware: Do Not Skip This Section

What You Need Before Running a Single Command

• A running Proxmox VE server (any recent version)
• Minimum 2 vCores allocated (4 vCores recommended for heavy automations)
• Minimum 4 GB RAM allocated (8 GB recommended)
• Minimum 64 GB of fast storage, SSD or NVMe only — absolutely no HDDs
• Router access to configure a static IP address

A Note on Storage: The Single Biggest Mistake New Users Make

The helper script defaults to a 32 GB disk. That sounds reasonable until you see what HAOS actually stores: a recorder database logging every sensor state change, local backups, system logs, and add-on data. Users on Reddit consistently report hitting a full disk within two to four weeks on the 32 GB default. Use 64 GB as your minimum. Use 128 GB if you are running multiple add-ons and long recorder history.

Method 1: The Quick Start (Newbie Nora’s Path)

Two Beginner Options, And Why We Steer You Away From One of Them

Option A: Buy a Home Assistant Green

The Home Assistant Green is a plug-and-play hardware appliance. You plug it in, connect it to your network, and follow the onboarding wizard. No Proxmox required, no command line, no configuration files. It is officially supported by Nabu Casa, the company behind Home Assistant.

The trade-off is flexibility. The Green runs only Home Assistant. You cannot run Jellyfin, Nextcloud, or any other self-hosted service alongside it on the same hardware. If you want a dedicated, zero-maintenance smart home hub and nothing else, this is a valid choice.

Option B: Home Assistant as a Docker Container

• No Supervisor layer
• No Add-on Store (no one-click Zigbee2MQTT, no one-click ESPHome)
• USB antenna passthrough becomes a manual configuration nightmare
• Every future integration update requires manual dependency management
• No built-in backup system managed by the Supervisor

If you are already running Proxmox, skip both options above and go directly to Method 2.

When Method 1 Actually Makes Sense

• You do not own a Proxmox server and are not planning to build one
• You want zero maintenance overhead and a supported appliance
• You are testing Home Assistant before committing to a full hardware investment

Method 2: Install Home Assistant OS HAOS Proxmox VM — Pro Setup

This is the standard for self-hosters. HAOS runs as a full virtual machine, giving you the complete Supervisor, the full Add-on Store, and clean isolation from your other Proxmox workloads. If you already have a Proxmox server running services like Jellyfin or Nextcloud, adding HAOS as a VM is the natural next step.

Step 1: Access the Proxmox Shell

1. Open your Proxmox web UI in a browser.
2. In the left sidebar, click your primary node. The default name is pve.
3. Click Shell in the top-right area of the node view. This opens the Proxmox host console directly.

Make sure you are in the node shell, not a VM console or LXC console. The prompt should show your Proxmox hostname, not a VM name.

Step 2: Run the Community Helper Script

The Proxmox VE Helper Scripts project, maintained at community-scripts on GitHub, is the community standard for installing HAOS on Proxmox. It handles image downloading, VM creation, and initial boot automatically.

A common Reddit confusion: use haos-vm.sh, not the deprecated haos.sh. The old URL returns a silent 404 and nothing happens. Use this exact command:

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

Paste this into the Proxmox shell and press Enter. If nothing happens and the prompt returns immediately, see the Troubleshooting section below. You are likely using the wrong URL or are in the wrong shell.

Step 3: Choose Advanced, Not Default

When the script starts, it will present you with a menu. Select Advanced to control every parameter before the VM is built.

Step 4: Configure VM Parameters the Right Way

When the Advanced configuration prompts appear, use these values:

Take your time on the storage pool selection. If you have multiple pools, identify which one is backed by SSD or NVMe before running the script. You can check this in the Proxmox UI under Datacenter > Storage.

Step 5: Let the Script Build and Boot the VM

After you confirm your configuration, the script takes over completely. It will:

1. Download the latest HAOS disk image directly from the Home Assistant release servers
2. Create the VM with your specified parameters
3. Import the disk image into your selected storage pool
4. Start the VM automatically

Expect this to take between 2 and 5 minutes depending on your internet speed and storage write speed. You will see progress output in the terminal. A successful run ends with the VM running and a confirmation message.

Configuration and Validation: Confirm Everything Works

Step 1: Read the IP Address From the VM Console

1. In the Proxmox left sidebar, find your new VM.
2. Click on it, then click the Console tab.
3. Wait approximately 60 seconds for HAOS to fully boot. You will see boot messages scroll by.
4. Once booted, the console displays the assigned IP address. It will look something like 10.10.10.x or 192.168.1.x depending on your network.

Write this IP address down. You need it for the next two steps.

Step 2: Lock In a Static IP via Router Configuration

The exact steps vary by router brand, but the process is universal:

1. Log into your router admin panel (typically at 192.168.1.1 or 192.168.0.1).
2. Find the DHCP reservation or static lease table. It may be labeled “Address Reservation”, “Static DHCP”, or “DHCP Binding” depending on your router.
3. Find the MAC address of the HAOS VM. You can see this in Proxmox under your VM’s Hardware tab, in the Network Device entry.
4. Create a reservation that maps that MAC address to the IP address you observed in the console.
5. Save and apply the settings.

Step 3: Complete the Home Assistant Onboarding Wizard

1. Open a browser on any device on your local network.
2. Navigate to:

http://[YOUR-IP-ADDRESS]:8123

3. The Home Assistant onboarding wizard will load. Create your admin account using a strong, unique password. Do not reuse a password from another service.
4. Set your home location precisely. Home Assistant uses this for sunrise and sunset automations. An incorrect location means your lights turn on at the wrong time, every single day.
5. Complete the wizard and confirm the main dashboard loads without errors.

Validation Checklist

Before moving on, confirm every item below:

• HAOS VM shows as running in the Proxmox VM list
• Console displays a valid local IP address
• Static IP configured in router for that IP
• Home Assistant UI accessible at http://[IP]:8123
• Admin account created with a strong password
• Home location set correctly in onboarding

The Honest Trade-offs: What a Full VM Costs You Compared to Docker

What You Give Up

• RAM overhead: A VM permanently reserves its allocated RAM. If you allocate 8 GB, those 8 GB are unavailable to your Proxmox host and other VMs, even when HAOS is idle. A Docker container shares host memory more efficiently.
• Boot time: A VM cold start takes 45 to 90 seconds. A Docker container starts in under 5 seconds.
• Disk footprint: A full VM image takes more raw storage space than a container filesystem.

Why You Should Pay That Cost Anyway

The Supervisor and Add-on Store are non-negotiable for a maintainable smart home. Without them, you are manually updating every integration, manually managing dependencies, and manually configuring USB antenna passthrough every time a driver changes. The r/homeassistant community consistently recommends HAOS over Container for any primary installation, and the reasoning is consistent: the maintenance burden of a Container setup compounds every month.

The hardware investment pays back in hours saved per month. This is the only setup we run at SelfHostHero, and it is the only setup we recommend to anyone building a smart home they plan to maintain long-term.

Troubleshooting Common Errors

Error: Script Does Not Start After Pasting Into Shell

Symptom: Nothing happens after pressing Enter, or the terminal returns to the prompt immediately with no output.

Cause: You are either using the deprecated haos.sh URL, which returns a silent 404, or you are pasting the command into a VM console instead of the Proxmox node shell.

Fix: Verify your command uses haos-vm.sh exactly as shown below, and confirm you are in the Proxmox node shell (the prompt shows your Proxmox hostname).

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

Error: Home Assistant Is Extremely Slow, Graphs Do Not Load

Symptom: The UI takes 10 or more seconds to respond. History graphs time out or never render. The system feels sluggish even with few devices connected.

Cause: During the Advanced configuration step, you selected an HDD-backed storage pool instead of an SSD or NVMe pool. HAOS writes sensor state data to disk continuously. A spinning disk cannot keep up with this write pattern.

Fix: There is no patch for this. You must rebuild the VM. Delete the existing VM, rerun the helper script, and explicitly select your SSD or NVMe pool during the Advanced configuration step.

Error: Home Assistant Unreachable After Router Reboot

Symptom: http://[IP]:8123 returns a connection refused error or times out after your router restarts.

Cause: Your router assigned a new IP address to the HAOS VM via DHCP after the restart. The IP you bookmarked no longer points to your Home Assistant instance.

Fix: Configure a static IP in your router as described in the Configuration and Validation section above. As a secondary layer of protection, you can also set a static IP directly inside Home Assistant under Settings > System > Network. Using both methods together means the IP will survive even if your router configuration is reset.

Conclusion and Next Steps: Your Smart Home Foundation Is Live

What You Have Built

• Home Assistant OS (HAOS) running as a full VM on Proxmox
• Sufficient RAM and fast SSD/NVMe storage (64 GB minimum) allocated
• Static network IP configured via router
• Initial admin account and home location onboarding completed

You now have a fully local smart home foundation with zero cloud dependency. Every byte stays on your hardware, on your network, under your control.

What Comes Next: The Server Is Running But Deaf and Blind

HAOS is running, but it currently has no way to communicate with your physical smart home devices. It cannot see your Zigbee light bulbs, your Z-Wave door sensors, or your smart energy meter. The next two steps in your build are:

1. USB Passthrough in Proxmox: Physically passing a Zigbee or Z-Wave USB dongle (a dual-chip antenna) through to the HAOS VM so it can communicate with your wireless devices. Without this step, your smart home hardware is invisible to Home Assistant.
2. Local Network Device Discovery: Discovering and integrating devices that are already on your local network, such as a smart P1 energy meter or local-only Wi-Fi sensors. Home Assistant will detect many of these automatically once it is running.

We will cover both of these in the next guides in this series. Your foundation is solid. Now we make it useful.