Installing Home Assistant OS.

When Home Assistant OS is the right path.

Home Assistant OS fits several specific situations.

Readers on tier-3 hardware. Raspberry Pi, Home Assistant Yellow, and Home Assistant Green are all best served by Home Assistant OS. The hardware's modest capacity does not support the graybox pattern, and the simpler install matches the tier-3 use case (hobbyist greenhouses, learning, backup systems, small deployments).

Readers who want an appliance experience. Some growers prefer software they do not have to administer beyond the Home Assistant interface. Home Assistant OS provides that — all management happens through the web interface, including updates, backups, and add-on installation. No command-line interaction required for normal operation.

Readers with a spare dedicated machine. A grower who has a machine they want to dedicate entirely to Home Assistant (an old tower that will run nothing else, a purpose-bought mini PC specifically for Home Assistant duty) can install Home Assistant OS directly. Simpler than Ubuntu plus Docker for a dedicated-machine deployment.

Readers who want the Supervisor. Home Assistant OS includes the Supervisor, which provides integrated add-on management, automatic updates, and built-in backup — all through the Home Assistant interface. The grower who values this integration is well-served by Home Assistant OS.

Backup or secondary systems. An operation with its primary deployment on tier-1 or tier-2 hardware may keep a tier-3 Home Assistant OS installation as a hot or cold standby. Fast to bring up from a backup, simple to maintain.

Home Assistant OS is not appropriate for the graybox pattern. Readers who want Home Assistant alongside Mosquitto, MariaDB, ESPHome, Frigate, and many other services on the same machine should use [Installing Home Assistant on Ubuntu with Docker](/home-assistant/installation/ha-docker) or [Installing Home Assistant Supervised](/home-assistant/installation/supervised) instead.

Supported hardware.

Home Assistant OS runs on specific hardware families.

Raspberry Pi 4 and Raspberry Pi 5 with adequate RAM (4 GB minimum, 8 GB preferred). Storage is typically microSD (not recommended for long-term use — see [Purpose-Built Home Assistant Hardware](/home-assistant/hardware/dedicated#the-pis-microsd-card-problem)) or SSD via USB (recommended) or NVMe via hat (on Pi 5).

Home Assistant Yellow and Home Assistant Green have Home Assistant OS pre-installed. The grower can typically skip the image-writing steps and go straight to onboarding.

Generic x86-64 hardware including mini PCs, repurposed business desktops and laptops, and Intel NUCs. Home Assistant OS runs directly on the machine as the sole operating system.

Virtual machines on hypervisors including Proxmox, VMware ESXi, Hyper-V, and VirtualBox. Home Assistant OS runs inside the VM; the host runs something else. Appropriate for readers who want Home Assistant OS's appliance experience while keeping the physical machine flexible.

Downloading the image.

Home Assistant OS images are distributed as files that get written to a storage device and booted. Download the image matching the target hardware from [home-assistant.io/installation](https://www.home-assistant.io/installation/).

For Raspberry Pi: Download the image marked "Raspberry Pi 4" or "Raspberry Pi 5" (64-bit). The file is typically named like `haos_rpi5-64-XX.X.img.xz` (where XX.X is the version number).

For generic x86-64: Download the image marked "Generic x86-64." Typically named like `haos_ova-XX.X.img.xz` or similar.

For virtual machines: Download the VMDK, OVA, QCOW2, or VHDX image matching the hypervisor.

The images are compressed (`.xz` format) and typically around 300 MB compressed, expanding to 6 to 8 GB when written.

Writing the image to storage.

The image-writing tool depends on the target hardware.

For Raspberry Pi: Balena Etcher ([etcher.balena.io](https://etcher.balena.io)) or Raspberry Pi Imager ([raspberrypi.com/software](https://www.raspberrypi.com/software/)) write the image to a microSD card or USB SSD connected to the grower's administration computer. The process is straightforward: select the image file, select the target storage device, confirm, wait. Writing takes 5 to 15 minutes depending on the speed of the storage device and the USB connection.

For generic x86-64: The image is written to a USB stick first, and then the target machine boots from that USB stick to install Home Assistant OS onto its internal storage. Balena Etcher handles this write. The boot-and-install process on the target machine takes 15 to 30 minutes.

For virtual machines: Import the image file into the hypervisor following the hypervisor's import documentation. Create a virtual machine that uses the imported disk image, allocate appropriate resources (4 GB RAM minimum, 32 GB disk minimum, 2 CPU cores), and start the VM.

After writing, insert the storage device in the target hardware (microSD in a Pi, USB stick in a generic x86-64 machine for the boot-and-install) and power it on.

First boot.

Home Assistant OS boots and performs initial setup automatically. During first boot, the system installs itself, fetches current configuration, and prepares the Home Assistant instance. This takes 5 to 20 minutes depending on hardware and network speed.

The grower does not need to interact with the console during this process. Home Assistant OS is headless by design — the web interface is the sole management surface. During first boot, a console display may show status messages, but these are informational only.

The system is ready when it responds on the network. The grower should be able to navigate to `http://homeassistant.local:8123` from another computer on the same network, or to the IP address Home Assistant OS acquired from DHCP (check the router for connected devices to find the address).

If `homeassistant.local` does not resolve (some networks do not support mDNS), use the IP address directly. A router's DHCP client list usually shows the Home Assistant OS device — the name will be something like `homeassistant`.

Onboarding.

The first visit to the Home Assistant web interface starts the onboarding flow.

Create the admin account. Enter a name, username, and password for the first user. This account has full administrative access. The password should be strong; the collective recommends a password manager for generating and storing it.

Provide location information. Country, time zone, elevation, unit preferences (metric or US customary), and optionally a name for the home (which Home Assistant uses throughout the interface). Location enables weather integrations, sun-related automations, and correct time-of-day behavior.

Share usage data (optional). Home Assistant asks whether to share anonymized usage statistics with the project. The collective recommends enabling this — it helps the project prioritize development and does not include personal data.

Device discovery. Home Assistant OS scans the local network for discoverable devices (cast receivers, printers, certain sensors, common smart home brands). The grower can configure some now or later; most will come later as specific integrations are set up.

Dashboard. After onboarding, the default Home Assistant dashboard appears. The installation is working.

Adding add-ons.

The Supervisor (part of Home Assistant OS) manages add-ons — additional services that integrate tightly with Home Assistant. Add-ons are accessed through Settings → Add-ons → Add-on Store.

Common add-ons for agricultural deployments:

Mosquitto broker. MQTT message broker. Required for ESPHome devices, Zigbee2MQTT, and any custom MQTT integrations.

ESPHome Builder. Manages ESPHome device firmware. Essential for growers building custom sensors and controls.

Zigbee2MQTT. Zigbee device management, for deployments using Zigbee sensors and controllers. Requires a Zigbee coordinator USB stick plugged into the host.

File editor. Web-based editor for Home Assistant configuration files, useful for edits that are easier in text than in the interface.

Samba share. Exposes Home Assistant's configuration directory as a network share for backup or for editing from another computer.

Terminal & SSH. Adds SSH access to the Supervisor's underlying shell. Useful for troubleshooting; not required for normal operation.

Studio Code Server. Full VS Code in the browser, for readers who prefer a more powerful editor for Home Assistant configuration.

Node-RED. Flow-based automation environment, integrating with Home Assistant.

Each add-on has its own configuration and its own documentation in the Add-on Store. Installing an add-on is a matter of clicking Install, waiting for the download, configuring the add-on's settings, and starting it.

Home Assistant OS is restricted in what add-ons it supports — the catalog is maintained by the Home Assistant project and community. For services not available as add-ons (or for full flexibility), the graybox pattern (Ubuntu plus Docker) provides broader options. This is the main tradeoff of Home Assistant OS.

Configuring backups.

Home Assistant OS has built-in backup functionality through the Supervisor. Configure it through Settings → System → Backups.

Local backups save to the Home Assistant OS filesystem. Useful for point-in-time recovery but vulnerable to hardware failure (the backup is on the same device that might fail).

Network backups copy to a network share (Samba, NFS). A separate always-on machine holds the backups, providing protection against local hardware failure.

Cloud backups through Nabu Casa sync backups to Home Assistant Cloud. Requires a Nabu Casa subscription.

External cloud storage (Google Drive, Dropbox, Nextcloud, WebDAV) is available through community add-ons. A grower can configure backups to sync to one of these services, providing offsite copies without the Nabu Casa subscription.

The collective's recommendation for Home Assistant OS deployments: local backups on a schedule (weekly or daily, depending on how much change the operation produces), plus one offsite destination (cloud service or network share on a separate machine). Before relying on the backup, test the restore process — boot a second Home Assistant OS instance, restore a backup, verify it worked. A backup that has never been tested is not a backup. [Backup and Recovery](/home-assistant/operations/backup) covers the strategy in depth.

Updates.

Home Assistant OS updates happen through the Supervisor. Core Home Assistant updates, Supervisor updates, and operating system updates each have their own update controls in Settings → System → Updates.

The collective recommends: wait a few days after a major Home Assistant release before applying it (to see if the community reports significant issues), read the release notes before updating (they document breaking changes), and keep backups current so recovery from a problematic update is straightforward.

Add-on updates are managed independently through the Add-on Store.

Home Assistant OS itself updates periodically with security patches and new features. These updates are generally low-risk but should be applied with the same caution as Home Assistant core updates.

[Updates and Version Management](/home-assistant/operations/updates) covers the practical rhythm for production systems.

Migrating from Home Assistant OS.

A common scenario: a grower starts with Home Assistant OS on a Raspberry Pi, outgrows the Pi, and migrates to more capable hardware running Ubuntu plus Docker. The migration is straightforward.

1. Take a full Home Assistant backup from the Home Assistant OS installation. 2. Copy the backup file to somewhere outside the Pi (cloud storage, another computer, a USB drive). 3. Install the new hardware per [Installing Ubuntu Server](/home-assistant/installation/ubuntu) and [Installing Home Assistant on Ubuntu with Docker](/home-assistant/installation/ha-docker). 4. Once Home Assistant is running on the new hardware, use its Supervisor (if using Supervised) or a manual restore process (if using Docker Compose) to restore the backup. 5. Move any USB devices (Zigbee coordinator, BLE adapter, AI accelerator) from the old hardware to the new. 6. Update any integrations that reference the host's IP address. 7. Decommission the old hardware (or keep it as a spare).

The migration typically takes an afternoon. The Home Assistant backup captures configuration, automations, integrations, dashboards, and history, making the new installation functionally equivalent to the old.

Common issues.

Home Assistant does not appear on the network after first boot. Check the router's connected devices list for a device named `homeassistant`. Confirm the storage device is fully seated (especially for microSD on a Pi). Confirm the hardware has power and network. First boot can take longer than expected on slower storage — wait 20 minutes before assuming something is wrong.

Web interface not accessible at `http://homeassistant.local:8123`. Some networks do not support mDNS (the `.local` resolution). Use the IP address directly: find it in the router's DHCP client list, or connect a monitor to the machine temporarily to see the IP address on the console.

Onboarding appears stuck. First boot initialization continues in the background during onboarding. A slow hardware platform (Raspberry Pi 4 with microSD) can take substantial time for the initial database setup. Wait 10 to 20 minutes before reloading the page.

microSD card appears corrupted over time. Home Assistant OS running from a microSD card on a Pi wears the card through database writes. The mitigation is to boot from an SSD instead. See [Purpose-Built Home Assistant Hardware](/home-assistant/hardware/dedicated#the-pis-microsd-card-problem) for the details.

Backup file too large to transfer. Home Assistant backups can reach several gigabytes over time, particularly if extensive add-on data is included. Split backups by contents (configuration only, history only) or exclude non-critical add-on data from specific backups. The backup configuration interface supports selective inclusion.