Installing Home Assistant Supervised.

What Home Assistant Supervised is.

Home Assistant Supervised consists of Home Assistant running in a Docker container, the Supervisor running in another Docker container, and a handful of supporting containers (the OS-Agent, audio handling, and related infrastructure), all managed together on a host operating system the grower administers directly. The installer script sets up the containers and the configuration; the grower then uses Home Assistant as they would on any other installation, with the add-on store, backup system, and update controls all available through the Home Assistant interface.

The key distinction from Home Assistant OS: the underlying operating system is a standard Ubuntu or Debian install, fully accessible to the grower. Other services (databases, media servers, file shares) can run alongside Home Assistant on the same machine, managed independently through Docker or as native services, while Home Assistant itself retains the appliance-style experience.

The key distinction from Home Assistant Container (bare Docker): the Supervisor is present. Add-ons install through the Home Assistant interface. Backups include configuration plus add-on data plus history in one archive. Updates happen with a click, coordinated across the Home Assistant and Supervisor versions.

Supervised is maintained officially by the Home Assistant project, but with conditions. The project supports Supervised specifically on Debian 12 (Bookworm) as the primary reference platform. Ubuntu 24.04 and similar Debian-derivatives work in practice but may receive less formal testing. Host configuration is opinionated: specific packages, specific kernel parameters, specific network and storage conventions. Deviations from the supported configuration can cause the Supervisor to flag the system as unsupported, which affects available functionality and support access.

When Supervised is the right path.

Supervised fits specific situations.

Growers who want the Supervisor experience on flexible hardware. The add-on store, integrated backups, and streamlined updates are valuable. Running these on Ubuntu rather than Home Assistant OS preserves the ability to run other services on the same machine.

Graybox deployments that want add-on convenience. A grower can run Home Assistant Supervised on Ubuntu and still install Mosquitto, ESPHome, Zigbee2MQTT, Node-RED, and others as Docker containers alongside. The Supervisor manages the Home Assistant stack; the grower manages the rest. Both can coexist on the same machine.

Readers migrating from Home Assistant OS who want Ubuntu access. A grower who started on a Raspberry Pi with Home Assistant OS and moved to more capable hardware can retain the Home Assistant OS experience on the new machine while gaining the flexibility of a real operating system underneath.

Specific integrations that benefit from Supervisor features. Some integrations rely on Supervisor-provided services (audio pipeline, OS-level permissions) that are available in Supervised and Home Assistant OS but not in bare Docker deployments.

Supervised is not the right path for:

Readers who want maximum flexibility with Docker Compose. The Docker graybox pattern (covered in Installing Home Assistant on Ubuntu with Docker) gives direct control over every container through docker-compose.yml. Supervised manages Home Assistant's containers through the Supervisor, which is less transparent.

Readers who want the simplest possible experience. Home Assistant OS is simpler than Supervised because it eliminates the host-OS layer entirely. For tier-3 hardware and appliance-style deployments, Home Assistant OS is usually preferable.

Readers who want an unopinionated Linux host. Supervised imposes specific host-configuration requirements. Readers who want a standard Ubuntu install where they control every aspect are better served by Docker Compose.

The collective's general guidance: Docker Compose for the fully-flexible graybox; Home Assistant OS for tier-3 hardware and dedicated machines; Supervised for the specific case where the Supervisor experience matters on a shared machine.

Supported operating systems and hardware.

Supervised officially supports:

Architectures. x86-64 (most common), ARM64 (Raspberry Pi 4/5 and similar), and a few others. The installer checks architecture automatically.

Hardware. Any hardware that runs the supported OS and meets the general requirements: 4 GB RAM minimum, 32 GB storage minimum, though the collective's recommendations are 16 GB RAM and 256 GB SSD for a graybox deployment as covered in Choosing Your Hardware.

The collective's recommendation when choosing between Debian and Ubuntu for Supervised: Ubuntu for most growers because of the broader documentation ecosystem and compatibility with the rest of this section's guidance, Debian for readers who specifically prefer Debian or want maximum alignment with the Supervised reference platform.

Before installing.

Prerequisites:

Ubuntu Server (or Debian) installed and updated. Per Installing Ubuntu Server. The system should be at the current LTS version, fully updated.

Network access configured. Static IP or DHCP reservation, SSH working, time zone set correctly.

Docker not yet installed. Docker CE must be installed before running the Supervised installer; the installer does not install Docker itself. Install Docker CE from Docker's official repository first (the get.docker.com convenience script is the documented path), then run the Supervised installer on the otherwise-clean system.

No other container managers. Portainer, standalone Docker Compose installations, and similar should not be present when the Supervised installer runs. After Supervised is running, additional Docker containers can be managed separately, but the initial installation should be on a clean system.

AppArmor enabled and working. Supervised requires AppArmor (a Linux security feature). Ubuntu Server has it enabled by default; verify with sudo aa-status.

systemd-resolved configured. The default Ubuntu configuration conflicts with some Supervised networking requirements. The installer may prompt for changes; check the current Supervised documentation for specifics.

A clear hour. First-time Supervised installation takes 30 to 60 minutes including reboot and onboarding.

Installing Home Assistant Supervised.

The installation runs through a script maintained by the Home Assistant project. The canonical source is https://github.com/home-assistant/supervised-installer.

# 1. Packages the Supervised installer depends on
sudo apt update
sudo apt install -y \
  apparmor jq wget curl udisks2 libglib2.0-bin \
  network-manager dbus systemd-journal-remote

# 2. Docker CE, which must be in place BEFORE the Supervised package
#    (the .deb does not install Docker; docker-ce is not in the default apt repos)
curl -fsSL https://get.docker.com | sh

# 3. OS-Agent: check the releases page for the current version and your architecture
wget https://github.com/home-assistant/os-agent/releases/download/1.6.0/os-agent_1.6.0_linux_x86_64.deb
sudo dpkg -i os-agent_1.6.0_linux_x86_64.deb

# 4. Home Assistant Supervised itself
wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
sudo apt install -y ./homeassistant-supervised.deb

The OS-Agent version above (1.6.0) is an example; the releases page at https://github.com/home-assistant/os-agent/releases lists the current version and the right file for the machine's architecture. Home Assistant officially validates Supervised against Debian; on Ubuntu it runs but sits slightly outside the supported set, which is worth weighing against the Docker path on the Docker install page.

Run the installer with sudo. The installer performs several actions:

1. Installs required packages (AppArmor, network tools, D-Bus, and others).
2. Installs the OS-Agent (a service that bridges Supervisor to the host OS).
3. Installs the Home Assistant Supervised package.
4. Downloads and starts the Home Assistant, Supervisor, and supporting containers.
5. Configures the system for Supervised operation (networking, AppArmor profiles, D-Bus permissions).

The installer prompts a few times: confirm the machine type (generic-x86-64 for a mini PC or desktop, raspberrypi4 or raspberrypi5 for a Pi). The installer runs through its steps and reports completion.

Reboot after installation:

sudo reboot

After the reboot, the Supervisor brings up Home Assistant. The first Home Assistant start takes a few minutes; subsequent starts are faster.

First access and onboarding.

Home Assistant is available at http://server-ip:8123 after the Supervisor has brought it up. Navigate there in a browser.

The Home Assistant onboarding flow is identical to Home Assistant OS: create the admin account, set location, choose preferences, optionally share usage data, review discovered devices.

After onboarding, the Home Assistant dashboard appears, now with the Supervisor's features visible in the Settings → Add-ons → Add-on Store interface.

Add-ons in Supervised.

The add-on store in Supervised works the same as in Home Assistant OS. The same add-ons are available: Mosquitto, ESPHome, Zigbee2MQTT, Node-RED, File Editor, Samba, Terminal & SSH, Studio Code Server, and many others. Installation, configuration, and management are all through the Home Assistant interface.

The add-on store in Supervised can install official add-ons (maintained by the Home Assistant project) and community add-ons (from community repositories the grower adds to the Supervisor). This is a broader catalog than Home Assistant OS effectively presents and a narrower catalog than the full Docker Hub available to Docker Compose deployments.

For services not available as add-ons, the grower can still run them as separate Docker containers managed outside the Supervisor (alongside Supervised but not through it). This is the graybox-adjacent pattern that Supervised enables. A typical setup might use the Supervisor for Home Assistant, Mosquitto, and ESPHome (all as add-ons), and Docker Compose for Frigate, Grafana, and InfluxDB (managed directly by the grower).

Updates in Supervised.

Home Assistant core updates, Supervisor updates, and add-on updates all happen through the Home Assistant interface, similar to Home Assistant OS. The underlying Ubuntu host updates separately, through normal apt update and apt upgrade workflows.

The collective's update recommendations for Supervised:

Home Assistant core updates. Read release notes before applying. Wait a few days after major releases for community reports of issues. Apply updates through the interface.

Supervisor updates. Usually low-risk and apply automatically by default. Review in the interface if the grower prefers manual control.

Add-on updates. Review each add-on's release notes. Update during operational downtime if possible.

Ubuntu host updates. Weekly or monthly apt update && apt upgrade as normal. Reboot after kernel updates to apply them. Coordinate reboots with Home Assistant operations: automations pause during the reboot, so timing matters for critical periods.

Backups in Supervised.

Supervised includes the Supervisor's backup system: complete snapshots including Home Assistant configuration, automations, history, and add-on data. Backup destinations mirror Home Assistant OS: local, network share, Nabu Casa cloud, or community add-ons to external services (Google Drive, Dropbox, Nextcloud, WebDAV).

In addition, because the host is a general-purpose Ubuntu system, the grower can implement host-level backups (filesystem snapshots, rsync to external storage, full-disk images) that complement the Supervisor backups. For serious production deployments, both layers of backup provide defense against different failure modes.

Backup and Recovery covers the strategy.

Comparing Supervised to the alternatives.

A direct comparison of the three Ubuntu-based installation paths.

Home Assistant on Ubuntu with Docker (graybox). Maximum flexibility. The grower writes docker-compose.yml and controls every container directly. Add-ons are not available: every service is a separate Docker container the grower manages. Backups are host-level (tar of the graybox directory); no Supervisor-integrated backups. Updates are docker compose pull && docker compose up -d. Best for readers who want direct control and are comfortable with Docker Compose.

Home Assistant Supervised. Middle ground. The Supervisor manages Home Assistant and add-ons through the Home Assistant interface. Other Docker containers (Frigate, Grafana, InfluxDB) can run alongside, managed separately. Backups include Home Assistant and add-ons; separate host-level backups cover everything else. Updates happen through the interface for Home Assistant and add-ons, through apt for the host. Best for readers who want the Supervisor experience with Ubuntu underneath.

Home Assistant OS on dedicated hardware. Simplest. The machine runs Home Assistant OS exclusively. Add-ons through the interface, no direct OS access. Backups integrated. Updates integrated. No other services on the same machine. Best for tier-3 hardware and for readers who want appliance-style operation.

All three produce a working Home Assistant. The choice depends on how much direct control the grower wants and whether other services need to run on the same machine.

Common issues.

"System is unsupported" warning. The Supervisor displays this when the host configuration deviates from expected. Common causes include unsupported OS version, missing required packages, disabled AppArmor, kernel settings that conflict with expected values. The Supervisor's system health panel details the specific issues. Addressing them returns the system to supported status.

AppArmor-related failures. If AppArmor is disabled or misconfigured, Supervised does not install or runs with warnings. Re-enable AppArmor with sudo systemctl enable --now apparmor.

Existing Docker conflicts. If Docker was installed before the Supervised installer, conflicts can arise. Uninstall Docker first: sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin, then run the Supervised installer fresh.

Network discovery not working. Supervised uses Network Manager for some operations, which can conflict with Ubuntu's default systemd-networkd. Following the installer's network configuration recommendations addresses most cases.

Supervisor updates breaking functionality. Supervisor releases occasionally introduce regressions. The release notes track these. Rolling back a Supervisor update is not straightforward; waiting for the fix release is usually the answer. Keep recent backups as a worst-case recovery path.

Migration between installation paths.

Moving between Home Assistant OS, Supervised, and Docker is straightforward because the Home Assistant backup format is identical across all three.

HAOS to Supervised. Take a full backup on Home Assistant OS. Install Supervised on the new (or same) hardware following this page. Restore the backup through the Supervisor's backup interface. Move USB devices, update integration IPs as needed.

Supervised to Docker. Take a full backup. Install Docker with Compose following Installing Home Assistant on Ubuntu with Docker. Start Home Assistant in Docker. Restore the backup through the Home Assistant interface. Note: add-on data in the backup does not restore into a Docker deployment because the add-on system is not present; each service that was an add-on needs to be set up separately as a Docker container.

Docker to Supervised. Less common but possible. Take a Home Assistant backup through the interface. Uninstall Docker on the host. Install Supervised. Restore the backup. Add-ons that the grower previously managed as separate Docker containers can be reinstalled through the Supervisor's add-on store or continued as separate containers.

Migration typically takes an afternoon. Backup and Recovery covers the mechanics.