The Home Assistant Operating System is a Linux-based operating system built specifically to host Home Assistant and its Apps, intended for people running Home Assistant on a single-board computer such as a Raspberry Pi or ODROID, or on an x86-64 machine with UEFI firmware.

What it is

Home Assistant Operating System, formerly known as HassOS, is a Linux-based operating system optimized to host Home Assistant and its Apps. It is a project from the Open Home Foundation, is written primarily in Python, and is licensed under Apache-2.0. It is not based on a regular Linux distribution such as Ubuntu; it is built using Buildroot. Docker is its container engine, and by default it deploys the Home Assistant Supervisor as a container, which in turn uses Docker to control Home Assistant Core and Apps in separate containers. The system targets single-board computer devices such as the Raspberry Pi or ODROID, and it also supports x86-64 systems with UEFI firmware.

The concrete problem it addresses is the host platform rather than the application. A general-purpose Linux distribution carries a broad set of components and update mechanisms that have nothing to do with running a home automation server, and this project replaces that general-purpose distribution with a Buildroot-built system optimized for Home Assistant. The result is a platform that is lightweight and memory-efficient, with minimized I/O, and updates that are delivered over the air or from USB through RAUC rather than through the package management of a conventional distribution. Read-only SquashFS file systems using LZ4 compression, together with ZRAM for /tmp, /var and swap, keep the running system small, while AppArmor provides a Linux kernel security module for the containerized components. Support for new hardware is deliberately gated: the list of supported hardware is defined by ADR-0015, and every new addition must meet the requirements of ADR-0017 and pass through an architecture design proposal.

Key capabilities

• Over The Air (OTA) updates and offline updates, both handled by RAUC, including USB updates.
• Docker Engine as the container platform, with the Home Assistant Supervisor deployed as a container by default.
• Supervision of Home Assistant Core and Apps as separate Docker containers, keeping components modular.
• A Buildroot LTS Linux base rather than a general-purpose distribution.
• SquashFS for read-only file systems with LZ4 compression, and ZRAM for /tmp, /var and swap with LZ4 compression.
• Bootloaders split by hardware: GRUB for devices that support UEFI and U-Boot for devices that do not.
• AppArmor as the Linux kernel security module for the running system.

Who uses it and how

• Households running Home Assistant as an appliance on a Raspberry Pi or ODROID, where the operating system is installed once and updated over the air rather than administered as a general-purpose server.
• x86-64 users with UEFI firmware who want the same appliance-style deployment on small form factor or mini-PC hardware.
• Installations with limited or no network access, which rely on offline and USB update paths instead of downloading over the air.
• Users who extend Home Assistant through Apps, each running in its own container controlled by the Supervisor rather than sharing a single runtime.
• Developers and embedded engineers contributing to the platform, who use the manually triggered development build GitHub Action workflow to produce development builds published at os-artifacts.home-assistant.io.

Getting started

The official getting started guide and installation instructions at home-assistant.io take you through downloading Home Assistant Operating System and getting it running on your machine. Development builds produced by the development build GitHub Action workflow are available at https://os-artifacts.home-assistant.io/index.html.

How it compares

The README draws the boundary itself: this is not a regular Linux distribution like Ubuntu, but a Buildroot-built system whose components, bootloaders, file systems and update mechanism are chosen for one workload. Where a general-purpose distribution is assembled and maintained as a general computing platform, this project is distributed as an image that runs Home Assistant and its Apps in Docker containers under the Supervisor, with RAUC handling updates.

When to use it — and when not to

Choose it when the goal is an appliance that runs Home Assistant with over-the-air updates and minimal administration, and when the hardware is already covered by the supported board list defined in ADR-0015. It is a poor fit for anyone who wants a general-purpose Linux host, who needs a board that has not passed the ADR-0017 hardware screening and the associated architecture design proposal, or who is unwilling to work with a Buildroot-based stack. Contributors should note that the README itself recommends prior experience with embedded systems, Buildroot and the Linux distribution build process, and that board-level detail lives in the Home Assistant Developer Docs rather than in this repository.