The Comprehensive Architecture of Home Assistant Supervised and Dockerized Deployments

The landscape of smart home automation is defined by the tension between ease of use and granular control. At the center of this ecosystem lies Home Assistant, a platform that offers various installation trajectories depending on the user's technical proficiency and hardware goals. One of the most complex and often misunderstood methods of deployment is the Supervised installation. This method attempts to bridge the gap between the streamlined experience of Home Assistant OS (HAOS) and the flexibility of a standard Linux distribution. By integrating a Supervisor container into a Debian environment, users can theoretically enjoy the "Add-on" ecosystem while maintaining root access to the underlying host operating system. However, this hybrid approach introduces significant architectural constraints, strict system requirements, and a precarious relationship with the Docker engine that can lead to system instability if not managed with extreme precision.

Conceptualizing Home Assistant Supervised vs. Home Assistant Container

To understand the Supervised method, one must first distinguish it from the standalone Container installation. Home Assistant Container is a pure Docker deployment where the Home Assistant Core runs as a single container. In this scenario, there is no Supervisor. The absence of the Supervisor means that the "Add-ons" tab within the Home Assistant user interface is completely missing. Add-ons are, in reality, just Docker containers that the Supervisor manages on your behalf. When running Home Assistant Container, a user is responsible for manually deploying, configuring, and updating any additional services they require.

Home Assistant Supervised, conversely, is an installation method that runs a Docker-based version of Home Assistant exclusively on Debian. Its defining characteristic is the inclusion of the Supervisor container. The Supervisor acts as a system manager, providing a layer of orchestration that allows users to install Add-ons directly from the UI. These Add-ons are Docker-based applications specifically designed to interact with the Supervisor. Because the Supervisor expects a very specific environment to function, it monitors the host system for compatibility.

The technical implication of this architecture is a rigid dependency on the host OS. While Home Assistant Container can run on almost any distribution that supports Docker, the Supervised method is strictly tied to Debian. This is because the Supervisor requires specific system components to manage network interfaces, storage, and container lifecycles. The impact for the user is a trade-off: you gain the convenience of the Add-on store, but you lose the freedom to use non-Debian distributions or to modify the host system without risking an "Unsupported" or "Unhealthy" system status.

The Mechanics of the Supervised Installation Process

Installing Home Assistant Supervised is an advanced procedure that requires a deep understanding of Linux networking and Docker orchestration. It is not a simple "plug-and-play" process; rather, it is a manual configuration of the host environment to meet the strict requirements of the Supervisor.

The process begins with the critical transition of networking services. Standard Debian installations often use the ifupdown service for network configuration. However, the Home Assistant Supervisor requires NetworkManager and systemd-resolved to manage the network stack. This is necessary because the Supervisor must be able to dynamically manage network interfaces and DNS settings for the containers it spawoys.

The initial networking commands are executed as follows:

apt install network-manager systemd-resolved

Following this installation, the system typically loses internet connectivity because systemd-resolved is not yet configured to handle the existing DNS setup. To restore connectivity and finalize the transition to NetworkManager, the existing /etc/network/interfaces configuration must be disabled to prevent conflicts with ifupdown.

The commands to finalize the network transition are:

systemctl restart systemd-resolved.service && \
systemctl disable --now networking.service && \
mv /etc/network/interfaces /etc/network/interfaces.disabled && \
systemctl restart NetworkManager

This transition has a real-world consequence: the machine may be assigned a new IP address by the DHCP server, as NetworkManager appears as a different client to the router compared to the previous ifupdown configuration.

Once the networking layer is stabilized, the system must be prepared with necessary dependencies. These include curl for downloading installers and udisks2 for managing storage devices, which the Supervisor utilizes for disk operations.

apt install curl udisks2

The installation of the Docker engine is performed using the official Docker convenience script:

curl -fsSL get.docker.com | sh

Before the final Home Assistant package can be installed, the OS-Agent must be deployed. The OS-Agent is a critical piece of software that allows the Supervisor to communicate with the host operating system, providing the Supervisor with telemetry and control over the hardware.

Finally, the Supervised Debian package is downloaded and installed. The user must select the correct image based on their hardware architecture. The supported architectures include:

generic-x86-64
odroid-c2
odroid-c4
odroid-n2
qemuarm-64 (for aarch64 machines)
qemux86-64
raspberrypi3-64
raspberrypi4-64
raspberrypi5-64
khadas-vim3

The installation command is:

curl -L -o homeassistant-supervised.deb https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
apt install ./homeassistant-supervised.deb

For advanced users who wish to change the default data storage path from /var/lib/homeassistant (formerly /usr/share/hassio) to a custom location, the installation can be modified:

DATA_SHARE=/my/own/homeassistant dpkg --force-confdef --force-confold -i homeassistant-supervised.deb

The "Unsupported" System Trap and Supervisor Constraints

A primary challenge with the Supervised installation is the Supervisor's aggressive monitoring of the Docker environment. The Supervisor is designed to be the sole orchestrator of the system. If it detects other Docker containers that were not installed through the Supervisor's own Add-on system, it may flag the system as "Unsupported" or "Unhealthy."

Common Docker-based applications that can trigger these warnings include:

Portainer
Watchtower

When a system is marked as "Unsupported," it means the installation no longer adheres to the strict guidelines required for official support from the Home Assistant development team. If the system is marked as "Unhealthy," the Supervisor may actually block the user from performing updates until the incompatibility is resolved.

This creates a significant conflict for users who want a "hybrid" server—a machine that runs Home Assistant alongside other independent services like Samba, MiniDLNA, or CUPS. While it is technically possible to run these services on the host, the Supervisor's intolerance for external Docker management makes the Supervised method a precarious choice for those who treat their server as a general-purpose Linux box.

Migration Strategy: Moving from Supervised to Pure Docker

Due to the restrictive nature of the Supervised method and the announcement that support for this method will be limited or removed after January 2026, many expert users are migrating to a pure Docker (Container) setup. This transition involves moving away from the Supervisor entirely and managing services as individual Docker containers or stacks.

The first step in this migration is the total decommissioning of the Supervised environment. This requires stopping the Home Assistant core and disabling the underlying system services that the Supervisor relies on.

sudo ha core stop
sudo systemctl disable --now hassio-supervisor.service hassio-apparmor.service

Once the services are disabled, any remaining Supervised containers must be identified and terminated:

sudo docker ps
sudo docker stop <ID_or_Name> <ID_or_Name> ...

To fully clean the system and remove the old images, the following commands are used:

sudo docker ps -a
sudo docker rm ID_or_Name ID_or_Name ...
sudo docker image prune -a
sudo docker system prune

Reconstructing the Add-on Ecosystem with Independent Containers

The most significant loss when moving from Supervised to Container is the loss of Add-ons. However, since Add-ons are simply Docker containers, they can be replaced by standalone versions of the same software.

The following table outlines the mapping between Supervisor Add-ons and their standalone Docker equivalents:

Supervisor Add-on	Standalone Docker Replacement	Primary Function
Configurator	File Editor	Direct configuration file management
SSL Proxy / Let's Encrypt	NGINX Proxy Manager	SSL termination and reverse proxy
Mosquitto Add-on	Eclipse Mosquitto	MQTT Broker for device communication
Zigbee2MQTT Add-on	Zigbee2MQTT	Zigbee gateway management
Backup Add-on	Duplicati	Configuration and data backups
SQLite	SQLite Web	Database viewing and management

To manage these containers, experts often use Dockge, a lightweight alternative to Portainer that focuses on Docker Compose stacks, providing a clean interface for managing .yaml files.

The structural preparation for this new environment requires a dedicated directory hierarchy to ensure data persistence and organization:

sudo mkdir -p /opt/{dockge,stacks,haoss/{nginx-proxy-manager/{data,letsencrypt},homeassistant/config,mosquitto/{config,data,logs},zigbee2mqtt/data,duplicati/{config,backup},sshterminal}}

For users migrating ZigBee2MQTT, the configuration files must be manually moved from the old Supervisor volume to the new directory:

sudo cp -aRv [source_path] [destination_path]

Advanced Container Management and Maintenance

In a pure Docker environment, the user assumes the role of the Supervisor. This requires a shift in how permissions and updates are handled. To ensure the containers have the necessary access to the filesystem, it is often necessary to set the User ID and Group ID to root:

PUID=0 PGID=0

This configuration ensures that the container can access all necessary files on the host without permission errors, although it requires strict security auditing.

Because there is no "Update" button in the Home Assistant UI for standalone containers, users must implement a manual or semi-automated update strategy. One effective method is the use of the dockcheck script, which scans for available image updates.

The installation of dockcheck is performed via:

curl -L https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh -o ~/.local/bin/dockcheck.sh
chmod +x ~/.local/bin/dockcheck.sh

To check for updates, the user simply runs:

dockcheck.sh

For data integrity, the use of Duplicati is recommended. Unlike the integrated Home Assistant backup system, Duplicati must be configured to target specific container configuration directories. A robust backup job should include the following paths:

/opt/stacks/
/opt/dockge/
/opt/haoss/configurator/
/opt/haoss/duplicati/
/opt/haoss/mosquitto/
/opt/haoss/nginx-proxy-manager/
/opt/haoss/sshterminal/
/opt/haoss/zigbee2mqtt/

Addressing the "Docker-in-Docker" Fallacy

A common point of confusion for beginners is the desire to run the Home Assistant Supervisor inside a Docker container. This request is fundamentally flawed due to the architectural requirements of the Supervisor. The Supervisor is not just a regular application; it is an orchestrator that requires direct access to the Docker socket (/var/run/docker.sock) and the host's network stack to manage other containers.

Attempting to run the Supervisor inside another container would create a "Docker-in-Docker" (DinD) scenario. While technically possible by pulling a Debian or Ubuntu image and executing the install script within it, this approach is highly redundant and inefficient. It adds a layer of virtualization that complicates networking and volume mapping without providing any actual benefit. The Supervisor is designed to be the primary manager of the host's Docker engine, not a guest within another container.

Conclusion

The choice between Home Assistant Supervised and Home Assistant Container is a choice between convenience and control. The Supervised method provides a seductive "all-in-one" experience through the Add-on store, but it does so by imposing a rigid, fragile set of constraints on the host operating system. The requirement for a pristine Debian installation and the intolerance of the Supervisor toward external Docker containers make it a suboptimal choice for users who desire a multi-purpose server.

The industry trend is moving decisively toward the modular approach. By decoupling the Home Assistant Core from the Supervisor and managing dependencies via Docker Compose and tools like Dockge, users achieve a system that is faster, cleaner, and more transparent. The transition from a Supervised environment to a Containerized environment removes the risk of "Unsupported" system flags and grants the user absolute authority over their hardware. While the initial setup of standalone containers for MQTT, Zigbee, and Proxy management requires more effort, the resulting stability and flexibility far outweigh the initial convenience of the Supervised installation.