# Home Assistant OS

> What Home Assistant OS is made of, how it boots, and how its repository is organized.

Source: https://contributors.home-assistant.io/os/operating-system/

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](https://buildroot.org/), 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.

## What is in it

- **Bootloader**: [GRUB](https://www.gnu.org/software/grub/) on UEFI systems (x86-64, generic Arm, and virtual machines), [U-Boot](https://docs.u-boot.org/) 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`](https://github.com/home-assistant/operating-system/blob/dev/Documentation/kernel.md) in the repository lists the current versions.
- **Root file system**: [EROFS](https://docs.kernel.org/filesystems/erofs.html), 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](https://rauc.io/), with two system slots. See [the update system](https://contributors.home-assistant.io/os/operating-system/update-system/).
- **Security**: the [AppArmor](https://apparmor.net/) 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](https://github.com/home-assistant/os-agent) repository. The Supervisor uses it over D-Bus for host tasks, like moving the data disk.

## How it boots

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](https://contributors.home-assistant.io/os/operating-system/partitions/).
3. `haos-config.service` imports a `CONFIG` USB drive, if one is plugged in. See [configure the host](https://contributors.home-assistant.io/os/operating-system/configuration/).
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.

## The repository

[home-assistant/operating-system](https://github.com/home-assistant/operating-system) uses Buildroot's [br2-external mechanism](https://buildroot.org/downloads/manual/manual.html#outside-br-custom): everything specific to Home Assistant OS lives outside Buildroot, in [`buildroot-external/`](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external). Buildroot itself is a Git submodule in [`buildroot/`](https://github.com/home-assistant/operating-system/tree/dev/buildroot), pointing at the [home-assistant/buildroot](https://github.com/home-assistant/buildroot) fork. That fork carries as few patches on top of upstream as possible.

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

## Where to go next

- [Build an image](https://contributors.home-assistant.io/os/operating-system/build/) to get a working setup.
- [Supported boards](https://contributors.home-assistant.io/os/operating-system/boards/) lists every build target.
- [Releases and builds](https://contributors.home-assistant.io/os/operating-system/releases/) explains how your change ends up in a release.

## All pages in this section

### Guides

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

### Reference

- [Partitions](https://contributors.home-assistant.io/os/operating-system/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](https://contributors.home-assistant.io/os/operating-system/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](https://contributors.home-assistant.io/os/operating-system/board-metadata/): The variables in the meta file of every board, and the version file shared by all of them.

### Boards

- [Supported boards](https://contributors.home-assistant.io/os/operating-system/boards/): Every board Home Assistant OS builds for, with its build target, bootloader, and machine type.
- [Raspberry Pi](https://contributors.home-assistant.io/os/operating-system/raspberry-pi/): Raspberry Pi specifics for Home Assistant OS, like the serial console, I2C, and booting from USB.
- [ODROID](https://contributors.home-assistant.io/os/operating-system/odroid/): Hardkernel ODROID specifics for Home Assistant OS, like eMMC installation, the boot flow of the M1 and M1S, and the consoles.
- [Generic systems](https://contributors.home-assistant.io/os/operating-system/generic/): The generic x86-64 and aarch64 targets, for PCs and other systems that boot with UEFI.
- [Virtual machines](https://contributors.home-assistant.io/os/operating-system/virtual-machine/): The ova target, the virtual disk formats it builds, and what a virtual machine needs to run Home Assistant OS.