Why Home Assistant Supervised in Compose Is a Dead End

A reproducible Compose file cannot turn an unsupported Home Assistant installation into a supportable one. Use Home Assistant OS when Supervisor and add-ons are required, or use Home Assistant Container and own the surrounding services explicitly.

I updated the repository before I questioned the premise

The repository started in 2019 as a way to get the full Hass.io experience onto a plain container host. That was attractive: one Compose service could launch Supervisor, and Supervisor could create Home Assistant plus its add-on containers through the Docker socket.

Seven years later, the obvious maintenance work was still straightforward. I changed the Supervisor image from an old Docker Hub reference to ghcr.io, pinned it to 2026.04.0, removed the obsolete Compose version key, and set restart: unless-stopped. I also wrote a helper that can start the stack, wait for port 8123, report related containers, and distinguish an ordinary restart from a forceful cleanup.

One image-family assumption even failed during that update. I initially changed the Home Assistant repository from qemux86-64 to an amd64 name that looked more natural for bare-metal x86 hardware. Supervisor expected a :landingpage tag that image family did not provide, so I reverted to qemux86-64-homeassistant. That is exactly the sort of private contract an unsupported stack makes me own.

This is not ordinary Home Assistant Container

The important distinction is hidden by the word “Docker.” Home Assistant Container runs Home Assistant Core as a container on a Linux host I maintain. It does not include Supervisor or the managed app store. That is a current, supported installation method.

This repository does something else. It launches Home Assistant Supervisor in a privileged container, mounts the host Docker socket and system D-Bus socket, and lets Supervisor create more containers outside Compose’s ownership.

privileged: true
security_opt:
  - seccomp:unconfined
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket

That arrangement creates two control planes. Compose knows about the Supervisor container. Supervisor knows about Home Assistant and its apps. Stopping the Compose project does not automatically mean every child is stopped, and manually removing a child can leave Supervisor’s view of the system out of step with Docker’s.

The startup script also clears Supervisor’s saved last_boot value before launch. That was a practical workaround for container recreation, but it is another sign that the installation is imitating an environment Supervisor expected to control.

The support decision changed after this idea was useful

Home Assistant deprecated the Core and Supervised installation methods in 2025 and ended support with the 2025.12 release. The project’s current explanation is unusually clear: Home Assistant OS is recommended for almost everyone, while Home Assistant Container is intended for people who already run Docker and accept responsibility for the host and surrounding services.

The deprecation announcement did not say custom installations would instantly stop running. It said issue reports would no longer be accepted and recommended migration to OS or Container. That difference matters: “still starts” is not the same promise as “supported through future changes.”

I can keep chasing image tags, startup assumptions, D-Bus behavior, and Supervisor health checks. I cannot turn that maintenance into upstream support by making the Compose file cleaner.

My decision tree now has only two branches

The choice is not “easy versus advanced.” Home Assistant OS in a virtual machine can still leave the physical host available for other work while giving Supervisor the environment it expects. Container can be the cleaner advanced choice when I prefer explicit services and already know how I will replace the jobs previously handled by apps.

I would not rebuild the same stack just to avoid buying hardware

This is not an argument for throwing away a capable computer. Home Assistant OS can run on supported 64-bit hardware or in a VM, and Home Assistant Container can run on an existing Linux host. The migration choice and the hardware purchase are separate decisions.

For an always-on box, I care more about idle power, storage health, backup recovery, and the number of jobs sharing one failure mode than benchmark performance. My old-PC payback guide and calculator compares the electricity difference with replacement cost; it does not assume a new mini PC automatically pays for itself.

The backup is the migration plan, not the Compose file

Before changing installation types, I would create a full Home Assistant backup, download it somewhere outside the current host, and verify that I can actually read the archive. Home Assistant’s migration guidance uses restore from backup during onboarding on the replacement installation.

I would also record everything the old host provides outside Home Assistant: USB radio mappings, serial device paths, reverse-proxy names, local DNS entries, manually managed containers, and any directories that were mounted beside the main configuration. A Home Assistant backup cannot restore a neighboring service it never owned.

Then I would test the new installation before retiring the old one. The checks that matter in this house are concrete:

• Caséta, Matter, Bond, WLED, and Eufy entities return with the expected names.
• Automations survive a reboot and fail clearly when an optional device is unavailable.
• Local backups leave the Home Assistant machine.
• USB radios retain stable paths and do not depend on enumeration order.
• The old host stays intact until the new instance has survived an ordinary week.

I have not performed that production migration for this article, so I am not publishing a fake step-by-step victory lap. This is the decision the repository evidence supports: the Compose stack can be maintained, but I would spend the effort moving off it instead.

What happens to the repository

I am keeping the repository public because old infrastructure can still explain a real system, a compatibility failure, or a migration. I would change its front page to make the 2026 status impossible to miss and point new installations at the two supported choices.

I would not publish another version bump as proof that the method is current. A pinned image can make a deployment reproducible; it cannot make the architecture supported. The useful artifact now is the boundary it exposes: one Compose service was quietly responsible for a privileged second orchestrator, and every upstream assumption became part of my maintenance load.

Disclosure: I maintain the linked repository. I reviewed its code and history for this article but did not reinstall it on a production Home Assistant system.