Home Assistant OS

Home Assistant OS is a Linux system with one job: running Home Assistant. It is not based on a distribution like Debian or Ubuntu. It is built from source with Buildroot, one image per board, with only what Home Assistant needs.

Buildroot is a build system, not a distribution. It cross-compiles a toolchain, the kernel, a bootloader, and every package, and puts them together into a disk image. That makes it a good fit for small Arm boards, where building on the device itself would take forever.

• Bootloader: GRUB on UEFI systems (x86-64, generic Arm, and virtual machines), U-Boot on most single board computers, and the firmware's own tryboot mechanism on Raspberry Pi 5.
• Kernel: mainline Linux on most boards, and the Raspberry Pi fork of Linux on Raspberry Pi and Home Assistant Yellow. Documentation/kernel.md in the repository lists the current versions.
• Root file system: EROFS, compressed and read-only.
• Init and services: systemd, with NetworkManager for networking, systemd-timesyncd for time, and BlueZ for Bluetooth.
• Containers: the Docker engine, which runs the Supervisor and everything it manages.
• Updates: RAUC, with two system slots. See the update system.
• Security: the AppArmor kernel security module, with profiles for the Supervisor and apps.
• Memory: ZRAM for /var and /tmp, and a swap file on the data partition.
• OS Agent: a small program in the os-agent repository. The Supervisor uses it over D-Bus for host tasks, like moving the data disk.

1. The bootloader picks a slot, A or B, and boots its kernel and root file system.
2. systemd mounts the overlay and data partitions, and binds the persistent folders into place. See partitions.
3. haos-config.service imports a CONFIG USB drive, if one is plugged in. See configure the host.
4. Docker starts, and haos-supervisor.service starts the Supervisor container, hassio_supervisor. If the image is missing or broken, the service downloads a fresh one first.
5. The Supervisor marks the slot as good with RAUC, and starts its plugins, Home Assistant Core, and the apps.

A fresh image contains the Supervisor and its plugins already, but not Home Assistant Core. It ships a small landing page instead. On first start, the Supervisor downloads the latest Core, so every new installation starts on a current version.

home-assistant/operating-system uses Buildroot's br2-external mechanism: everything specific to Home Assistant OS lives outside Buildroot, in buildroot-external/. Buildroot itself is a Git submodule in buildroot/, pointing at the home-assistant/buildroot fork. That fork carries as few patches on top of upstream as possible.

Path	What it holds
buildroot-external/configs/	One <target>_defconfig per build target
buildroot-external/board/	Per board: metadata, boot files, kernel config, and hooks
buildroot-external/kernel/	Kernel config fragments shared by all boards
buildroot-external/package/	Extra packages, like hassio (preloads the Supervisor) and os-agent
buildroot-external/rootfs-overlay/	Files copied into every image, like the haos-* systemd units
buildroot-external/genimage/	The disk layout, see partitions
buildroot-external/ota/	The RAUC configuration, update manifest, and certificates
buildroot-external/meta	The OS version and deployment type
scripts/	Helper scripts, like enter.sh for the build container
tests/	Automated tests that boot the image in QEMU

• Build an image to get a working setup.
• Supported boards lists every build target.
• Releases and builds explains how your change ends up in a release.

• Build an image: Set up the build container and build Home Assistant OS for a board.
• Test your build: Boot your image in QEMU, run the automated tests, and install your build on a real device.
• Configure the host: Change host settings on Home Assistant OS with a CONFIG USB drive, or directly in the persistent folders on the host.
• Configure networking: How Home Assistant OS manages the network with NetworkManager, and how to configure what the UI does not cover.
• Debug the host: Get a root shell on Home Assistant OS over SSH or a console, and find the logs you need.
• Releases and builds: How a change to Home Assistant OS goes from a pull request to a release, with the branches, version numbers, and build pipelines involved.

• Partitions: The disk layout of Home Assistant OS, what each partition holds, and how the data disk feature moves the data partition.
• The update system: How Home Assistant OS updates itself with RAUC and two boot slots, how bundles are signed, and how to install your own build.
• Board metadata: The variables in the meta file of every board, and the version file shared by all of them.

• Supported boards: Every board Home Assistant OS builds for, with its build target, bootloader, and machine type.
• Raspberry Pi: Raspberry Pi specifics for Home Assistant OS, like the serial console, I2C, and booting from USB.
• ODROID: Hardkernel ODROID specifics for Home Assistant OS, like eMMC installation, the boot flow of the M1 and M1S, and the consoles.
• Generic systems: The generic x86-64 and aarch64 targets, for PCs and other systems that boot with UEFI.
• Virtual machines: The ova target, the virtual disk formats it builds, and what a virtual machine needs to run Home Assistant OS.