Home Assistant Operating System — Administrator & Developer Guide

1. Architecture Overview

Home Assistant Operating System (HAOS) is a Buildroot-based Linux distribution purpose-built to host the Home Assistant ecosystem. It provides a minimal, hardened, and fully managed OS that boots directly into a Docker-based service stack running the Home Assistant Supervisor, Core, and add-ons.

Design Philosophy

HAOS is not a general-purpose Linux distribution. It is an appliance OS:

• The root filesystem is read-only (squashfs/erofs)
• User data lives on a separate data partition (/mnt/data)
• Configuration persistence uses bind mounts from the data partition to /etc paths
• System updates are atomic A/B slot swaps via RAUC — no package manager
• All user-facing services (Home Assistant, add-ons) run as Docker containers
• The OS handles only hardware, networking, storage, and container orchestration

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        User Browser                         │
│                    homeassistant.local:8123                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────┐
│                    Docker (containerd)                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐│
│  │  Supervisor   │ │     Core     │ │   Add-ons (DNS,     ││
│  │  (hassio_     │ │  (home-      │ │   Audio, CLI,       ││
│  │  supervisor)  │ │  assistant)  │ │   Observer, etc.)   ││
│  └──────┬───────┘ └──────────────┘ └──────────────────────┘│
│         │  manages all containers                           │
└─────────┼───────────────────────────────────────────────────┘
          │
┌─────────┴───────────────────────────────────────────────────┐
│                  HAOS (Buildroot Linux)                      │
│  ┌────────────┐ ┌──────────────┐ ┌────────────────────────┐│
│  │ systemd    │ │ NetworkMgr   │ │ RAUC (OTA updates)     ││
│  │ services   │ │ (networking) │ │ A/B slot management    ││
│  └────────────┘ └──────────────┘ └────────────────────────┘│
│  ┌────────────┐ ┌──────────────┐ ┌────────────────────────┐│
│  │ AppArmor   │ │ os-agent     │ │ zRAM / swap           ││
│  │ (security) │ │ (D-Bus API)  │ │ (memory management)   ││
│  └────────────┘ └──────────────┘ └────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
          │
┌─────────┴───────────────────────────────────────────────────┐
│                   Disk Partition Layout                      │
│  boot │ kernel.0 │ system.0 │ kernel.1 │ system.1 │ data   │
│  (FAT)│  (A)     │  (A)     │  (B)     │  (B)     │ (ext4) │
└─────────────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Note

HAOS uses Buildroot (not Yocto/OpenEmbedded). Buildroot produces a complete cross-compiled root filesystem image from source. The buildroot/ directory is a git submodule pinned to a specific Buildroot release, and buildroot-external/ contains all HAOS customizations using Buildroot's external tree mechanism (BR2_EXTERNAL).

2. System Requirements

Build Requirements

Building HAOS requires a Linux host (or Docker on any platform):

The repository includes a Dockerfile for reproducible builds and a Makefile with board-specific targets.

Test Requirements

The test suite (tests/) requires:

Target Hardware Requirements

3. Configuration Reference

Partition Layout

HAOS uses a fixed partition scheme created by genimage during the build:

Important

The partition table type varies by board: GPT for UEFI systems (hdimage-gpt.cfg), hybrid MBR/GPT for some ARM boards (hdimage-hybrid.cfg), and pure MBR for legacy boards (hdimage-mbr.cfg). The genimage configs in buildroot-external/genimage/ define the exact layout for each type.

Disk Image Generation Configs

Systemd Service Units

HAOS defines a comprehensive set of systemd services in buildroot-external/rootfs-overlay/usr/lib/systemd/system/:

Core OS Services

Data and Storage Services

Persistent Bind Mounts

Memory Management Services

Other Services

Note

Many upstream systemd services have drop-in overrides in subdirectories (e.g., docker.service.d/, NetworkManager.service.d/). These customize behavior without modifying the original unit files. For example, docker.service.d/hassos.conf sets Docker dependencies and resource limits, and docker.service.d/failure.conf configures restart behavior on failure.

Systemd Presets

The file buildroot-external/rootfs-overlay/usr/lib/systemd/system-preset/70-haos.preset controls which services are enabled by default at boot.

System Configuration Files

Sysctl Settings

System Configuration Overrides

Tmpfiles Configuration

Tip

To understand the full boot sequence, trace the systemd dependency chain starting from hassos-data.service → hassos-expand.service → hassos-overlay.service → hassos-config.service → hassos-supervisor.service. The bind mount units depend on hassos-bind.target, ensuring data is available before services that need persistent state.

4. Deployment & Scaling

Building HAOS Images

Containerized Build (Recommended)

The repository includes a Dockerfile and Makefile for reproducible builds:

make <board_target>

Where <board_target> is one of the defconfig names in buildroot-external/configs/:

Build Process Flow

make <target>
  → Docker container with Buildroot toolchain
    → BR2_EXTERNAL=buildroot-external
      → buildroot-external/configs/<target>_defconfig
        → Cross-compile kernel, packages, root filesystem
          → buildroot-external/scripts/post-build.sh
            → Root filesystem overlay applied
          → buildroot-external/scripts/post-image.sh
            → genimage creates disk image
            → RAUC bundle created (.raucb)
            → hassos-hook.sh (board-specific post-processing)
              → Compressed image (.img.xz) output

Development Shell

Enter the Buildroot build environment interactively:

scripts/enter.sh

This launches a Docker container with the build environment mounted, allowing direct access to Buildroot's make menuconfig, make linux-menuconfig, and other build system commands.

Board Support Architecture

Each supported board has a directory under buildroot-external/board/ containing:

Note

The hassos-hook.sh script for each board implements two functions: hassos_pre_image() (copies bootloader, DTBs, and firmware to the boot partition) and hassos_post_image() (post-processing like xz compression). The Raspberry Pi hook additionally enables 64-bit mode in config.txt for 64-bit board targets.

Raspberry Pi-Specific Configuration

The Raspberry Pi boards use a shared base configuration with per-variant overrides:

buildroot-external/board/raspberrypi/
├── config.txt              ← Shared RPi firmware config
├── cmdline.txt             ← Shared kernel command line
├── hassos-hook.sh          ← Shared build hook
├── kernel.config           ← Shared kernel config fragment
├── uboot-boot.ush          ← U-Boot script (32-bit)
├── uboot-boot64.ush        ← U-Boot script (64-bit)
├── uboot.config            ← U-Boot config
├── rpi3-64/meta            ← RPi 3 metadata
├── rpi4-64/meta            ← RPi 4 metadata
├── rpi5-64/                ← RPi 5 (has own cmdline, config, hook)
│   ├── cmdline.txt
│   ├── config.txt
│   ├── hassos-hook.sh
│   └── rootfs-overlay/usr/lib/rauc/
│       ├── cmdline.sh      ← RAUC cmdline update hook
│       └── rpi-tryboot.sh  ← RPi 5 tryboot mechanism
└── yellow/                 ← HA Yellow (CM4/CM5 carrier board)
    ├── config.txt
    ├── cmdline.txt
    ├── patches/            ← Yellow-specific kernel & U-Boot patches
    └── rootfs-overlay/     ← Yellow firmware (brcmfmac)

Important

The Raspberry Pi 5 uses a different boot mechanism (tryboot) instead of U-Boot for slot switching. The rpi-tryboot.sh RAUC hook script manages this. This is why rpi5-64 has its own hassos-hook.sh separate from the shared RPi hook.

5. Operations

OTA Update System (RAUC)

HAOS uses RAUC for over-the-air updates with an A/B partition scheme.

RAUC Configuration

The RAUC system configuration template is at buildroot-external/ota/system.conf.gtpl and defines:

• Slot definitions (kernel.0, kernel.1, system.0, system.1)
• Keyring for bundle signature verification
• Status file location for boot tracking
• Bundle format and compatibility string

Signing Infrastructure

Warning

RAUC bundles are cryptographically signed. The three CA certificates (release, development, provisioning) form a trust chain. Only bundles signed with a trusted key are accepted for installation. Modifying or removing these certificates will break the OTA update mechanism.

Update Flow

1. Supervisor checks version.home-assistant.io for updates
2. Downloads .raucb bundle for the board
3. RAUC verifies bundle signature against trusted CA chain
4. RAUC installs kernel + system to INACTIVE slot (A→B or B→A)
5. RAUC marks new slot as primary boot target
6. System reboots into new slot
7. If boot succeeds → new slot marked "good"
8. If boot fails → bootloader falls back to previous "good" slot

Service Management

Supervisor Lifecycle

The Supervisor is managed by hassos-supervisor.service, which:

1. Depends on Docker being ready
2. Runs /usr/sbin/hassos-supervisor to start the Supervisor container
3. The Supervisor then manages all other containers (Core, add-ons, plugins)

The Supervisor container is tagged as ghcr.io/home-assistant/{arch}-hassio-supervisor:latest during the build process by buildroot-external/package/hassio/dind-import-containers.sh.

Key OS Scripts

Tip

The boot sequence flows: hassos-data.service (initialize data) → hassos-expand.service (expand partition) → hassos-overlay.service (overlay setup) → bind mounts → hassos-config.service (apply config) → docker-prepare.service → docker.service → hassos-supervisor.service. Tracing this chain is essential for debugging boot failures.

Container Image Pre-loading

During the build, HAOS pre-loads Docker container images into the data partition to enable offline first boot. The process is managed by three scripts in buildroot-external/package/hassio/:

1. fetch-container-image.sh — Downloads container images using skopeo with architecture-aware selection and retry logic (3 retries with exponential backoff). Uses file locking to prevent race conditions during parallel downloads.

2. dind-import-containers.sh — Runs inside a Docker-in-Docker container during the build. Loads pre-fetched OCI archives into the Docker daemon and tags the Supervisor image with the expected naming convention.

3. create-data-partition.sh — Creates and populates the data partition image:

   • Creates a 1280 MB ext4 image labeled hassos-data
   • Mounts and populates with Docker images via DinD
   • Sets up initial AppArmor profiles from version.home-assistant.io
   • Writes the updater channel configuration (updater.json)
   • Creates the .docker-use-containerd-snapshotter marker file

Note

The data partition image created during build contains pre-loaded container images so the system can boot without internet. The initial size is 1280 MB but is expanded to fill the disk on first boot by hassos-expand.service.

Monitoring and Health

The test suite validates these health indicators that administrators should also monitor:

• No failed systemd units: systemctl list-units --state=failed should report 0 failures
• No systemd dependency cycles: Check journalctl -b0 | grep 'ordering cycle'
• Kernel not tainted: cat /proc/sys/kernel/tainted should be 0
• Network connectivity: nmcli network connectivity check should report full
• No AppArmor denies: journalctl -t audit | grep DENIED should return empty
• Supervisor health: ha resolution healthcheck should pass with no unhealthy/unsupported entries
• RAUC slot status: rauc status should show active slot with correct version and no warnings

6. Performance

Memory Management

HAOS implements several memory optimization strategies:

zRAM

Two zRAM devices are configured by hassos-zram (/usr/libexec/hassos-zram):

zRAM provides transparent compression of temporary data, reducing disk I/O and extending the effective memory capacity on memory-constrained devices.

Multi-Generation LRU (MGLRU)

The haos-mglru.service enables the Multi-Generation LRU page reclaim algorithm, which improves memory management efficiency compared to the traditional LRU, particularly beneficial for systems running many containerized services.

Swap File

The swap file at /mnt/data/swapfile provides additional virtual memory. The size is managed by haos-swapfile.service reading /etc/default/haos-swapfile. Swap aggressiveness is tuned via /usr/lib/sysctl.d/15-swappiness.conf.

Docker Optimization

• Containerd snapshotter backend: Enabled when the .docker-use-containerd-snapshotter marker exists on the data partition, improving container layer handling
• journald logging: Docker uses journald as the log driver, eliminating separate log files and enabling unified log access through journalctl
• overlay2 storage driver: Efficient copy-on-write filesystem for container layers
• Resource limits: Docker service drop-ins in docker.service.d/resource.conf configure resource constraints

7. Security

AppArmor

HAOS uses AppArmor to provide mandatory access control for containerized services. The hassos-apparmor.service loads profiles at boot via /usr/libexec/hassos-apparmor. AppArmor profiles for the Supervisor are downloaded from version.home-assistant.io during the build and stored at /mnt/data/supervisor/apparmor/.

Warning

AppArmor denies indicate a container attempted an operation outside its allowed profile. Check journalctl -t audit | grep DENIED to diagnose. Persistent denies after updates may indicate a profile mismatch — the Supervisor manages profile updates automatically.

Filesystem Protection

• Read-only root: The system partition is squashfs/erofs, preventing runtime modification
• Persistent overlay: Only /etc changes persist via the overlay partition
• Bind mounts: Specific directories (/var/lib/docker, /var/lib/bluetooth, etc.) are bind-mounted from the data partition, isolating persistent state
• Separate data partition: User data, Docker containers, and add-ons live on a separate ext4 partition, preventing system corruption from data issues

OTA Update Security

• Signed bundles: All RAUC update bundles are cryptographically signed
• Certificate chain: Three-tier CA (release, development, provisioning) for different deployment stages
• Verification on install: RAUC validates the bundle signature before writing to disk
• Rollback protection: Failed boots automatically revert to the last known-good slot

Network Security

• mDNS only: The system is discoverable via mDNS (.local) only, not via LLMNR
• Dropbear SSH: Minimal SSH server with persistent host keys via bind mount, configured via drop-in overrides for security hardening
• NTP dispatcher: The NetworkManager dispatcher (10-ntp) ensures time synchronization updates when network state changes, preventing time-skew-based attacks

Docker Security

• AppArmor profiles per container: Managed by the Supervisor
• Container isolation: Each add-on runs in its own container with defined capabilities
• Docker daemon patches: HAOS applies custom patches to Docker (in buildroot-external/patches/docker-engine/) including:
  • Respecting explicit AppArmor profiles on privileged containers
  • Protecting bridge subnets from direct external access

Caution

The Docker engine patches in buildroot-external/patches/docker-engine/ modify upstream Docker behavior. Patch 0002-bridge-protect-bridge-subnet-from-direct-external-ac.patch adds firewall rules to prevent external access to the Docker bridge subnet. Removing this patch would expose container networks to the local network.

8. Developer Internals

Repository Structure

home-assistant/operating-system/
├── Dockerfile                  ← Build container definition
├── Makefile                    ← Board-specific build targets
├── README.md                   ← Project overview
├── .gitmodules                 ← Buildroot submodule reference
├── .hadolint.yaml              ← Dockerfile linter config (ignores DL3008)
├── buildroot/                  ← Buildroot (git submodule)
├── buildroot-external/         ← HAOS customization layer
│   ├── Config.in               ← Kconfig menu for HAOS packages
│   ├── external.desc           ← Buildroot external descriptor
│   ├── external.mk             ← Buildroot external makefile
│   ├── busybox.config          ← BusyBox configuration
│   ├── meta                    ← Project metadata
│   ├── board/                  ← Per-board configurations
│   │   ├── arm-uefi/           ← Generic ARM UEFI boards
│   │   ├── hardkernel/         ← ODROID boards
│   │   ├── khadas/             ← Khadas VIM boards
│   │   ├── nabucasa/           ← NabuCasa Green
│   │   ├── pc/                 ← x86-64 and OVA
│   │   └── raspberrypi/        ← RPi 3/4/5/Yellow
│   ├── bootloader/             ← MBR images, U-Boot config
│   ├── configs/                ← Buildroot defconfigs
│   ├── genimage/               ← Disk image layout configs
│   ├── kernel/                 ← Kernel config fragments
│   ├── ota/                    ← RAUC config, CA certs, hooks
│   ├── package/                ← Custom packages
│   │   ├── bluetooth-rtl8723/  ← RTL8723 Bluetooth driver
│   │   ├── eq3_char_loop/      ← eQ-3 HomeMatic kernel module
│   │   ├── gasket/             ← Google Coral TPU driver
│   │   ├── generic_raw_uart/   ← Generic raw UART driver
│   │   ├── hailo-pci/          ← Hailo AI accelerator PCI driver
│   │   ├── hailo8-firmware/    ← Hailo-8 firmware blobs
│   │   ├── hardkernel-boot/    ← Hardkernel bootloader
│   │   ├── hassio/             ← Supervisor container pre-loading
│   │   ├── khadas-boot/        ← Khadas bootloader
│   │   ├── lxd-guest-agent/    ← LXD VM guest agent
│   │   ├── os-agent/           ← Home Assistant OS Agent
│   │   ├── pi-bluetooth/       ← Raspberry Pi Bluetooth
│   │   ├── qemu-guest-agent/   ← QEMU VM guest agent
│   │   ├── rockchip-blobs/     ← Rockchip binary firmware
│   │   ├── rpi-eeprom/         ← RPi EEPROM update tools
│   │   ├── rpi-rf-mod/         ← RPi RF module (HomeMatic)
│   │   ├── rtl88x2bu/          ← Realtek Wi-Fi driver
│   │   ├── tempio/             ← Template I/O (host tool)
│   │   ├── udisks2/            ← UDisks2 (patched for HAOS)
│   │   ├── vcgencmd/           ← VideoCore GPU command tool
│   │   └── xe-guest-utilities/ ← Xen VM guest utilities
│   ├── patches/                ← Patches for upstream packages
│   │   ├── docker-engine/      ← Docker security patches
│   │   ├── grub2/              ← GRUB enhancements
│   │   ├── libglib2/           ← GLib journal logging fix
│   │   ├── linux/              ← Kernel patches (IPv6 reachability)
│   │   ├── network-manager/    ← NM connectivity check fix
│   │   ├── rauc/               ← RAUC journal logging
│   │   ├── systemd/            ← systemd patches (hostname, journal, time)
│   │   ├── uboot/              ← U-Boot string-to-env command
│   │   └── uboot-tools/        ← fw_printenv lock file path
│   ├── rootfs-overlay/         ← Files overlaid onto root filesystem
│   │   ├── etc/                ← Configuration files
│   │   ├── mnt/                ← Mount point placeholders
│   │   └── usr/                ← Services, scripts, rules
│   └── scripts/                ← Build and utility scripts
├── Documentation/              ← Kernel version docs
├── scripts/                    ← Developer helper scripts
└── tests/                      ← Smoke and Supervisor tests

Package System

HAOS custom packages follow the Buildroot package convention:

Each package's .mk file defines:

• *_VERSION — upstream version to download
• *_SITE — download URL or GitHub repository
• *_DEPENDENCIES — build-time dependencies
• *_INSTALL_TARGET_CMDS — installation commands

Notable Custom Packages

os-agent (buildroot-external/package/os-agent/): The Home Assistant OS Agent provides a D-Bus interface for the Supervisor to communicate with the host OS. It handles OS operations like network management, disk operations, and system information queries.

hassio (buildroot-external/package/hassio/): Not a single binary but a set of build-time scripts that pre-load the Supervisor and plugin container images into the data partition. Contains create-data-partition.sh, dind-import-containers.sh, and fetch-container-image.sh.

udisks2 (buildroot-external/package/udisks2/): UDisks2 patched for HAOS with three patches:

1. Allow explicitly disabling libsystemd-login
2. Isolate authorization-specific functions
3. Make polkit dependency optional

These patches enable UDisks2 to run without a full login/session manager or polkit daemon.

Guest Agents: Three guest agent packages support different virtualization platforms:

• qemu-guest-agent — for KVM/QEMU VMs
• lxd-guest-agent — for LXC/LXD containers
• xe-guest-utilities — for Xen/XCP-ng VMs

Upstream Patches

HAOS patches several upstream packages to customize behavior:

Kernel Configuration

Kernel configuration uses a layered fragment approach:

1. Board-specific config (buildroot-external/board/<board>/kernel.config) — architecture and hardware-specific settings
2. Version fragments (buildroot-external/kernel/v6.12.y/) — per-kernel-version features:

Additional board-specific kernel patches are applied from buildroot-external/board/<board>/patches/linux/.

Note

The script buildroot-external/scripts/check-dotconfig.py (using the vendored kconfiglib.py) validates that all kernel config fragments are correctly applied to the final .config. This prevents silent config regressions.

Build Scripts

Testing Strategy

HAOS uses labgrid for hardware-in-the-loop testing, combined with pytest.

Test Architecture

pytest
  └── labgrid (test automation framework)
       ├── ShellDriver (serial/SSH console interaction)
       ├── qemu-strategy.yaml (QEMU VM target definition)
       └── qemu_shell_strategy.py (QEMU-specific strategy)

Tests interact with a running HAOS instance (real hardware or QEMU VM) via shell commands, using shell.run_check() for command execution and shell_json() for JSON-parsed output.

Test Suites

Smoke Tests (tests/smoke_test/):

Offline Test (tests/smoke_test/test_offline.py):

OS Update Tests (tests/smoke_test/test_os_update.py):

Supervisor Tests (tests/supervisor_test/):

Running Tests

cd tests
pip install -r requirements.txt
pytest --lg-env qemu-strategy.yaml smoke_test/
pytest --lg-env qemu-strategy.yaml supervisor_test/

Tip

The test_init test disables auto-updates before running the suite by setting auto_update: false in /mnt/data/supervisor/updater.json and restarting hassos-supervisor.service. This prevents background updates from interfering with test assertions.

Udev Rules

mDNS / DNS-SD

The file /usr/lib/systemd/dnssd/workstation.dnssd registers the system as a workstation service via DNS-SD, enabling automatic discovery on the local network.

Known Issues and Community Feedback

Based on GitHub issues tracked for this project:

Contributing

Development documentation is hosted at developers.home-assistant.io/docs/operating-system/. The documentation source is in a separate repository: home-assistant/developers.home-assistant.

The kernel versions used in the current branch are documented in Documentation/kernel.md.

9. Integration Points

Home Assistant Supervisor

The Supervisor communicates with the OS through:

• os-agent — D-Bus interface for host operations (network, disk, system info)
• Docker socket — Container lifecycle management
• journald — Centralized logging via systemd-journal-gatewayd
• /mnt/data — Shared data volume for add-on storage, backups, configuration

Virtualization Guest Agents

HAOS includes guest agent packages for major virtualization platforms:

These agents provide host-guest communication for operations like graceful shutdown, filesystem freeze, and guest information reporting.

Hardware Acceleration

HAOS includes drivers for hardware accelerators:

Home Automation Hardware