Home Assistant Operating System: a Buildroot image that exists to run one application

What Home Assistant OS is for, and who it is not for

The README is direct about the target: a Linux based operating system optimized to host Home Assistant and its Apps. It runs on single board computers such as the Raspberry Pi or ODROID, and on x86-64 systems with UEFI. Everything in the repository follows from that narrow scope.

The consequence is that this is not a distribution you log into and administer like Ubuntu. The README states plainly that Home Assistant Operating System is not based on a regular Linux distribution. There is no package manager for end users to reach for, no expectation that you will install a compiler or a database server alongside the appliance. If your plan is to run Home Assistant plus three unrelated services on the same box, this image is the wrong starting point, and a container host on Debian or Alpine would serve you better.

Who it is for: people who want Home Assistant running on dedicated hardware with updates delivered over the air, and who are willing to accept the constraints that come with an appliance image.

Buildroot, SquashFS and the container layering

The build system is Buildroot LTS, pulled in as a submodule and driven from the top-level Makefile. The Makefile sets BUILDROOT and BUILDROOT_EXTERNAL to directories inside the checkout, collects board targets from buildroot-external/configs/*_defconfig, and forwards unknown targets to Buildroot with BR2_EXTERNAL pointed at the external tree. Board definitions therefore live outside the upstream Buildroot tree, which is how the project keeps its own hardware support separate from the upstream release cadence.

On the running system, the layering is explicit in the README's component list. GRUB handles boot on UEFI devices, U-Boot on devices without UEFI. Read-only filesystems use SquashFS with LZ4 compression. /tmp, /var and swap are ZRAM, also LZ4. Docker Engine is the container platform, and by default the Supervisor runs as a container, which in turn drives Home Assistant Core and Apps as separate containers. RAUC handles over the air and USB updates. AppArmor provides the kernel-level confinement.

The read-only root is the design decision that shapes everything else. It makes an interrupted power cycle far less likely to leave a corrupted system, and it is why /var has to be a compressed RAM-backed filesystem rather than ordinary disk. The trade-off is memory: anything that writes heavily to /var consumes RAM, not disk.

Installing Home Assistant OS and reaching the Supervisor

The repository does not carry end-user installation steps. The README points to the official getting started guide and the installation instructions on home-assistant.io for downloading the image and getting it running. Follow those pages for the actual flashing procedure for your board.

What the repository does document is the development path. Development builds are produced by a manually triggered GitHub Actions workflow and published at os-artifacts.home-assistant.io. If you want to build an image yourself, the top-level Makefile is the entry point, and the target names come from the defconfig files under buildroot-external/configs. The Makefile warns that an output directory already configured for one target must be cleaned before building another:

make distclean

Building is done inside the container described by the repository Dockerfile. That image is Debian trixie with docker-ce, plus the Buildroot toolchain dependencies (build-essential, bc, binutils, cpio, e2fsprogs, file, git, graphviz, jq, ncurses-dev, patch, perl, pigz, python3, qemu-utils, rsync, skopeo, sudo, texinfo and others). It copies scripts/entry.sh to /usr/sbin/ and sets it as the entrypoint, then sets the working directory to /build.

Once a device is flashed and booted, the Supervisor is already running as a container, and Home Assistant Core and Apps are managed by it. You do not start those by hand.

Where the appliance model gets in your way

The read-only SquashFS root is the clearest limitation. Anything you would normally persist under / or /usr is off limits, and the documented writable areas are /tmp and /var, both ZRAM-backed. Writing large or long-lived data there spends RAM and is lost on reboot. For Home Assistant's own configuration that is fine, because the Supervisor manages a data partition, but for a sidecar process that keeps a local database on the root filesystem it is a dead end.

Hardware support is the second constraint, and it is deliberately gated. The README states that the supported hardware list is defined by ADR-0015, and that every new hardware addition must meet the requirements in ADR-0017 and pass through an architecture design proposal. That is a real barrier if you have an obscure board: it is not enough for Linux to boot on it. The README also does not document rollback behaviour for RAUC updates, so if downgrading after a bad update matters to you, that is a question to resolve before you rely on it.

Finally, the README does not describe a supported path for installing arbitrary distribution packages on a running system. If that is a requirement, this is the wrong tool, and a plain Debian or Alpine host running Home Assistant Container is the better fit.

How this differs from running Home Assistant Container on a normal host

The obvious alternative is Home Assistant Container on a general purpose Linux distribution. The difference is not the application, it is who owns the operating system. On Debian or Alpine you own kernel updates, the bootloader, the filesystem layout and the Docker installation, and you can install whatever else you like on the same machine. Home Assistant OS takes all of that over: RAUC delivers updates, the filesystem is read-only SquashFS, and the Supervisor is the single control point for Core and Apps.

That makes the two options good at different things. A general purpose host is better when the machine has other jobs, when you need packages the image does not ship, or when you want to pin a specific kernel. Home Assistant OS is better when the machine exists only to run Home Assistant and you would rather not think about patching it. The cost of the second choice is exactly the flexibility of the first.

A second comparison point is the build path itself. Because this project is Buildroot-based with board definitions under buildroot-external, adding a board means writing a defconfig and a Buildroot external tree entry, not writing an installer script for an existing distribution. That is a heavier lift, and it is the reason hardware additions go through a proposal process.

Licence, maintenance and what an upgrade costs you

The repository is licensed Apache-2.0, with the LICENSE file at the top level. Note that this covers the project's own code and configuration; the image it produces bundles Buildroot, the Linux kernel, Docker Engine, RAUC, AppArmor, GRUB or U-Boot, and those components carry their own licences, which are not enumerated in the README. If you redistribute a built image, the per-component licence obligations are the thing to check, and that is a question for your own counsel rather than something the README settles.

Maintenance looks current: the last push to the dev branch was on 2026-09-21, and 18.3 was released on 2026-09-17 after two release candidates. The release pattern, with rc1 and rc2 preceding the final tag, tells you something practical about upgrade cost. If you want to catch problems before they reach your device, tracking the release candidates is the mechanism the project provides. If you would rather not, waiting for the final tag is the conservative choice, and the README's silence on rollback means the decision carries some weight.

For contributors, the build cost is the real expense. A full Buildroot build pulls a large toolchain and compiles a kernel and root filesystem, and the Makefile's warning about stale output directories exists because mixing targets in one output directory produces confusing failures rather than clean errors.

Editorial conclusion

Adopt Home Assistant OS if your goal is a Home Assistant instance on a Raspberry Pi, ODROID or UEFI x86-64 box and you want OTA updates handled by RAUC rather than by you. Do not adopt it if you need a general purpose Linux server, extra packages installed from a distribution repository, or a writable root filesystem, because the design is a read-only SquashFS image with ZRAM for /tmp and /var. Before flashing anything, verify that your board appears in the hardware list defined by ADR-0015 and read the board page for that device in the Home Assistant Developer Docs, since the README defers board specifics to that site rather than repeating them here.

Frequently asked questions

Official sources

1. home-assistant/operating-system on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases