Home Assistant Supervised (legacy).

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 was maintained by the Home Assistant project with conditions (Debian as the reference platform, an opinionated host configuration, a "system is unsupported" flag when the host drifted). In May 2025 the project announced a six-month deprecation, and release 2025.12 removed support entirely, along with the Core installation method and all 32-bit architectures. The two supported methods today are Home Assistant OS and Home Assistant Container.

If you already run Supervised.

Nothing stops on the day support ends. The install keeps working, automations keep firing, and the add-ons you have keep running. What stops is the stream of updates: no new Home Assistant releases, no Supervisor updates, no security fixes. For a system that sits on a farm network for years, that is the part that matters, and it is the reason to plan a move rather than ride it out.

Pick the destination by what you want from the machine. If the machine's job is Home Assistant and the add-on store is what you value, the destination is Home Assistant OS, on bare metal or in a virtual machine on the same Ubuntu host. If the machine is a graybox that also runs Mosquitto, a database, Frigate, or other services, the destination is Home Assistant Container under Docker Compose, with each former add-on becoming a container in the same file.

Take a full backup first, and copy it off the machine. The Home Assistant backup format is the same across all installation methods, so the configuration, history, and automations restore cleanly on either destination. Add-on data restores only into Home Assistant OS; on Container, each former add-on is set up again as its own service.

Budget an afternoon. The move is a restore, not a rebuild. The "Migration between installation paths" section below has the steps.

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.

Kept for reference. These steps install an unsupported system that will not receive updates; use them only to understand an install you already have.

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 paths, kept so a grower can see what Supervised offered and which supported method replaces each part of it.

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. This was the appeal. It is no longer supported, so it is not a choice for a new install.

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. For a new install the choice is between the first and the third: Container if other services share the machine, Home Assistant OS if they do not (or if you run it in a virtual machine on the host that does).

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 off Supervised is straightforward because the Home Assistant backup format is identical across installation methods.

Supervised to Home Assistant OS. Take a full backup through Settings, System, Backups, and copy it somewhere off the machine. Install Home Assistant OS on the target (the same machine wiped clean, a virtual machine on the host, or new hardware) following Installing Home Assistant OS. On first boot, choose to restore from backup. Add-ons, their data, configuration, and history all come across. Move USB devices and update any integration that referenced the old IP address.

Supervised to Container (the graybox path). Take a full backup and copy it off the machine. Remove the Supervised installation (the installer's uninstall path, or a clean Ubuntu Server install per Installing Ubuntu Server). Follow Installing Home Assistant on Ubuntu with Docker, adding a Compose service for each add-on you relied on (Mosquitto, ESPHome, a database, Zigbee2MQTT). Start Home Assistant and restore the backup through the onboarding screen. Add-on data in the backup does not restore into a Container deployment because there is no add-on system; each replacement service starts from its own configuration.

Moving to Supervised. Not recommended for any reason. The method receives no updates.

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