Home Assistant Raspberry Pi 5: Complete Supervised Guide

Q: Can I run Home Assistant OS instead of Supervised?

Yes. Home Assistant OS is the simpler choice for a dedicated Pi. It provides the same add-on store and handles all system management automatically. Choose Supervised when you need to run other services on the same machine.

Q: Does the Pi 5 boot from NVMe natively?

Yes, with current EEPROM firmware from early 2024 or later. Update using sudo rpi-eeprom-update -a, set boot order to NVMe-first in raspi-config, and the Pi boots from NVMe without the microSD inserted.

Q: How much storage does Home Assistant need?

The base install uses under 5GB. The recorder database with 100 entities and 30-day retention uses 2-8GB. A 256GB NVMe drive is more than adequate for a home installation.

Q: What is the Supervisor and what does it do?

The Supervisor is a container management daemon that manages updates for Core and add-ons, monitors system health, handles backups, provides the add-on store, and exposes the Supervisor API. Without it, these functions must be handled manually.

Print 🖨 PDF 📄 eBook 📱

Home Assistant Raspberry Pi 5 with a Supervised install on NVMe gives you a self-hosted smart home platform that runs 24/7 with fast dashboard load times, reliable database writes, and full access to the add-on ecosystem, without locking you into the Home Assistant OS environment. The Supervised install runs on Debian Bookworm, which means you control the underlying OS while the Supervisor handles Home Assistant Core updates, add-on containers, and system health monitoring. This guide covers hardware selection, Debian on NVMe setup, Supervised install, configuration, integrations, and maintenance.

Key Takeaways

The Supervised install is officially supported only on Debian Bookworm with an unmodified Docker CE installation and Network Manager as the network stack. Deviating from these requirements causes the Supervisor to report an unhealthy system, which blocks updates.
NVMe storage via a PCIe HAT provides substantially better I/O performance than microSD or USB SSD. Home Assistant’s SQLite recorder database generates continuous write activity. MicroSD cards wear rapidly under this workload and produce noticeably slower dashboard performance compared to NVMe.
Take a full Supervisor backup immediately after a working install and before every Core update. The Supervisor backup includes your configuration, automations, add-on settings, and secrets. Restoring from backup to a fresh install recovers a complete working system in under 10 minutes.

Home Assistant Raspberry Pi 5: Installation Paths

Home Assistant offers four installation methods. Understanding what each provides helps avoid choosing the wrong one for your use case.

Install type	OS control	Supervisor	Add-on store	Best for
Home Assistant OS	None	Yes	Yes	Simplest setup, dedicated Pi
Supervised	Full	Yes	Yes	Dedicated Pi, maximum flexibility
Container	Full	No	No	Shared server, manual management
Core	Full	No	No	Advanced users, Python environment

The Supervised install is the right choice when you want the add-on store and Supervisor-managed updates but also need to run additional services on the Pi or prefer direct OS access. The trade-off is that the Supervisor performs system health checks. If Docker, Network Manager, or OS Agent configuration drifts from expected values, the Supervisor reports the system as unhealthy. On a dedicated Pi running only Home Assistant, this is rarely a problem in practice.

Hardware Preparation

The Pi 5 has a PCIe 2.0 connector that accepts NVMe M.2 drives via a compatible HAT or adapter. The official Raspberry Pi M.2 HAT+ is the most widely tested option and handles power delivery correctly. Third-party PCIe HATs from Pineberry, Pimoroni, and others also work well.

Stick to M.2 NVMe drives in the 250GB-1TB range from established manufacturers: Samsung 980, Kingston A2000, Crucial P3, or WD Blue SN580. Avoid DRAM-less ultra-budget drives under heavy sequential write workloads. SATA M.2 drives do not work in this slot. Home Assistant’s recorder database produces sustained random write activity, so drive endurance matters more than peak sequential speed.

Use the official 27W USB-C power supply. The Pi 5 combined with an NVMe HAT and active cooling draws significantly more than a Pi 4 setup. An undersized supply causes undervoltage events that corrupt the SQLite database. See Raspberry Pi Power Monitoring via USB for verification under load.

Install active cooling. The Pi 5 runs warmer than Pi 4 under sustained load, and Home Assistant with multiple add-ons and automations generates continuous background activity. See Raspberry Pi 5 Cooling Guide for tested options and fan curve configuration.

Samsung 980 SSD 1TB PCle 3.0x4, NVMe M.2 2280, Internal Solid Sta...

Samsung 980 SSD 1TB PCle 3.0×4, NVMe M.2 2280, Internal Solid Sta…

VIEW ON AMAZON

Raspberry Pi M.2 HAT

$27.99

VIEW ON AMAZON

Debian on NVMe

The Supervised installer requires Debian 12 Bookworm. Flash the Debian 12 ARM64 image to the NVMe drive using Raspberry Pi Imager with the NVMe connected via a USB adapter, or flash a microSD first and use it to write the image to the NVMe. The Raspberry Pi 5 can boot from NVMe directly with current EEPROM firmware.

Update the Pi 5 EEPROM to enable NVMe boot:

# Boot from microSD first, then update EEPROM
sudo apt update && sudo apt full-upgrade -y
sudo rpi-eeprom-update -a
sudo reboot

# After reboot, check the bootloader version
vcgencmd bootloader_version

# Set NVMe as first boot device
sudo raspi-config
# Advanced Options > Boot Order > NVMe/USB Boot

After setting boot order, shut down, remove the microSD, and boot from NVMe. Confirm the drive is mounted correctly:

lsblk
df -h

Add noatime,discard mount options to the root partition in /etc/fstab for better NVMe longevity. noatime prevents access time updates on every file read. discard enables TRIM:

# Edit /etc/fstab and add options to the root partition line:
# UUID=xxxx / ext4 defaults,noatime,discard 0 1
sudo mount -o remount /

Set a static IP using Network Manager. The Supervised installer requires Network Manager as the active network stack:

sudo nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.1.100/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns 1.1.1.1
sudo nmcli connection up "Wired connection 1"

Expected result: ip addr shows your chosen static IP on the wired interface. ping 1.1.1.1 and ping google.com both succeed, confirming routing and DNS are working.

Installing Home Assistant Supervised

Dependencies

sudo apt update && sudo apt install -y \
  apparmor \
  avahi-daemon \
  dbus \
  jq \
  network-manager \
  software-properties-common \
  curl \
  wget \
  udisks2 \
  systemd-journal-remote \
  systemd-resolved

# Install Docker CE (official install script -- not docker.io from apt)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Log out and back in so the Docker group membership takes effect. Confirm Docker is running:

docker run hello-world

OS Agent

OS Agent provides the D-Bus interface between the Supervisor and the host OS. Install the latest aarch64 release from the GitHub releases page:

# Check the latest version at:
# https://github.com/home-assistant/os-agent/releases/latest
# Replace the version number below with the current release

wget https://github.com/home-assistant/os-agent/releases/latest/download/os-agent_1.6.0_linux_aarch64.deb
sudo dpkg -i os-agent_1.6.0_linux_aarch64.deb

# Verify installation
gdbus introspect --system \
  --dest io.hass.os \
  --object-path /io/hass/os

Expected result: gdbus introspect returns a D-Bus interface definition. If it returns an error, OS Agent is not running. Check systemctl status haos-agent.

Supervised installer

wget -O homeassistant-supervised.deb \
  https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
sudo dpkg -i homeassistant-supervised.deb

The installer will prompt for the machine type. Select raspberrypi5-64. The installer then pulls all required Docker images and starts the Supervisor and Home Assistant Core containers. This takes 5-15 minutes depending on your internet connection.

# Monitor the install progress
docker ps
journalctl -u hassio-supervisor -f

Expected result: docker ps shows at least hassio_supervisor and homeassistant containers running. Navigate to http://<pi-ip>:8123 and the Home Assistant onboarding page loads. The initial setup takes 3-5 minutes while Core finishes initialising.

Home Assistant Raspberry Pi 5 Supervised stack diagram showing Debian OS Docker Supervisor Core and add-ons layers

Configuration

Initial setup

Work through the onboarding wizard to set your location, name, and initial account. The location is used for sunrise and sunset automations and weather integrations. Set it accurately. The account created here is the owner account with full admin access.

After onboarding, immediately:

Enable two-factor authentication under your user profile
Create a full Supervisor backup under Settings > System > Backups
Install the SSH and Web Terminal add-on for command-line access

Configuration files

All configuration lives in /config inside the Home Assistant container, which maps to the host filesystem. The key files:

File	Purpose
`configuration.yaml`	Main config, integrations, customisations
`secrets.yaml`	Credentials and tokens. Never commit to version control.
`automations.yaml`	Automation rules (auto-managed by UI)
`scripts.yaml`	Reusable action scripts
`scenes.yaml`	Scene definitions

Keep sensitive values in secrets.yaml and reference them with !secret key_name in configuration.yaml. This allows backing up and sharing configuration without exposing API keys, passwords, or webhook tokens.

Essential add-ons

Add-on	Purpose
SSH and Web Terminal	Command-line access to the host and container
Studio Code Server	Browser-based YAML editor with syntax checking
Samba Share	Network access to the /config directory
Mosquitto Broker	MQTT broker for Zigbee2MQTT, ESPHome, and custom devices
Zigbee2MQTT	Zigbee coordinator management and MQTT bridge

Integrations

Home Assistant discovers many devices automatically on the local network. Philips Hue bridges, Chromecast devices, TP-Link smart plugs, and others appear as discovered integrations under Settings > Devices and Services. Accept these or search for integrations by name if auto-discovery does not find a specific device.

Zigbee

Two options for Zigbee integration. ZHA (Zigbee Home Automation) is built into Home Assistant and requires no additional software. Plug in a compatible USB dongle and add the ZHA integration. Zigbee2MQTT is more feature-complete, works without Home Assistant, and exposes devices to any MQTT subscriber. For a full Zigbee2MQTT setup with the SONOFF CC2652 dongle, see Zigbee2MQTT Raspberry Pi.

ESPHome

ESPHome devices running the native API component are auto-discovered by Home Assistant and added with one click. No MQTT broker needed for this path. For building and managing ESPHome firmware, see ESPHome Raspberry Pi.

MQTT

Install the Mosquitto Broker add-on and configure the MQTT integration to use localhost as the broker. Devices and services that publish to MQTT topics are then discoverable by Home Assistant. For a hardened Mosquitto setup with TLS and ACL, see Mosquitto MQTT Raspberry Pi.

Thread and Matter

Install the Thread and Matter integrations for next-generation smart home devices. With a compatible USB Thread radio dongle, Home Assistant acts as a Thread border router and Matter controller. See Thread Matter Raspberry Pi for the full setup.

Remote Access

Three practical options for accessing Home Assistant away from home:

Nabu Casa: The official subscription remote access service. Handles TLS, subdomain, webhooks, and Google/Alexa integration automatically. No router port forwarding needed. Around $7/month.
NGINX Proxy add-on: Self-hosted HTTPS with Let’s Encrypt. Requires a domain name and ports 80/443 forwarded on the router. Caddy can also serve this role. See Caddy Reverse Proxy Raspberry Pi.
WireGuard VPN: No public exposure of the Home Assistant port. Connect to the home network via VPN and access http://<pi-ip>:8123 through the tunnel as if on the local network. See WireGuard Raspberry Pi.

The WireGuard approach is the most conservative from a security standpoint. Home Assistant is never exposed to the public internet. Nabu Casa is the most convenient if you are not comfortable with DNS and certificate management.

Maintenance

Updates

Update notifications appear in the Supervisor dashboard and in the Home Assistant notification panel. The update sequence is:

Take a full Supervisor backup before starting.
Update OS Agent on the host: sudo dpkg -i os-agent_x.x.x_linux_aarch64.deb
Update the Supervisor from the Supervisor dashboard.
Update Home Assistant Core from the Settings > System > Updates panel.
Update add-ons individually or use the bulk update option.

Update the Debian base separately:

sudo apt update && sudo apt upgrade -y

Do not update Docker CE or Network Manager through apt without checking the Home Assistant Supervised compatibility matrix first. Major version changes in either can cause the Supervisor to report the system as unhealthy.

Backups

Configure automated backups under Settings > System > Backups. Set a daily schedule and keep at least 7 copies. Download backups to an off-Pi location. The same drive that stores the backup is not protection against drive failure. The Google Drive Backup add-on (community store) handles automatic off-site upload.

Troubleshooting

Supervisor shows unhealthy

# Check Supervisor diagnostics
ha supervisor info

# Attempt automatic repair
ha supervisor repair

# Check which health check is failing
ha resolution info

The most common causes of an unhealthy Supervisor are: Network Manager not managing the primary interface, Docker installed from apt install docker.io rather than the official script, or OS Agent not running. Check each in that order.

Cannot access web UI

# Check all containers are running
docker ps

# Restart Core if the container is up but the UI is not responding
ha core restart

# Check Core logs
ha core logs

NVMe not recognised after reboot

# Check EEPROM firmware version
vcgencmd bootloader_version

# Update EEPROM if older than October 2023
sudo rpi-eeprom-update -a
sudo reboot

# Confirm boot order
sudo rpi-eeprom-config | grep BOOT_ORDER

BOOT_ORDER=0xf416 indicates NVMe first, then USB, then SD. If the value is different, run sudo raspi-config and set the boot order under Advanced Options.

Slow dashboard or database errors

Slow dashboard performance after months of use is usually the recorder database growing without bounds. Set a retention policy in configuration.yaml:

recorder:
  purge_keep_days: 30
  exclude:
    domains:
      - media_player
      - weather

Excluding high-frequency domains like media_player and weather from the recorder significantly reduces database growth without affecting automation history.

FAQ

Can I run Home Assistant OS instead of Supervised?

Yes, and for most users it is the simpler choice. Home Assistant OS flashes directly to the NVMe, handles all system management automatically, and provides the same add-on store. The trade-off is that you cannot run other services on the Pi alongside it and have no direct access to the underlying OS. If the Pi is dedicated to Home Assistant, HAOS is the recommended install method. Choose Supervised when you need to run other services on the same machine.

Does the Pi 5 boot from NVMe natively?

Yes, with current EEPROM firmware (any version from early 2024 or later). Update the EEPROM from a microSD boot using sudo rpi-eeprom-update -a, set the boot order to NVMe-first in raspi-config, and the Pi boots from NVMe on the next power cycle without the microSD inserted.

How much storage does Home Assistant need?

The base Home Assistant install with a handful of add-ons uses under 5GB. The recorder database grows with the number of entities and retention period. A typical home setup with 100 entities and 30-day retention uses 2-8GB for the database. A 256GB NVMe drive is more than adequate for a home installation with room for long-term growth.

Can I move from HAOS to Supervised?

Yes, by restoring a Supervisor backup. Take a full backup on HAOS, set up a fresh Supervised install on Debian, and restore the backup through the onboarding screen. All configuration, automations, and add-on settings restore from the backup. Registered devices may need to be re-authenticated after the move.

What is the Supervisor and what does it do?

The Supervisor is a container management daemon that runs alongside Home Assistant Core. It manages updates for Core and add-ons, monitors system health, handles backups, provides the add-on store, and exposes the Supervisor API used by the Home Assistant web interface for system management tasks. Without the Supervisor (Container or Core installs), these functions must be handled manually.

References

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 5 (8GB), official M.2 HAT+, Samsung 980 NVMe 256GB. Last tested OS: Debian 12 Bookworm. Home Assistant Supervised 2024.11, OS Agent 1.6.0.

Was this helpful?

Yes

Thanks for your feedback!