OS and Supervisor

Most people run Home Assistant on Home Assistant OS. They flash an image, plug in the device, and never think about Linux again. That works because of two projects working together:

• Home Assistant OS is a small, read-only Linux system built with Buildroot, a tool that builds a complete embedded Linux system from source. It boots the device, runs Docker, and updates itself with an A/B scheme: it has two copies of the system, A and B, writes an update to the one that is not running, and falls back to the other when the update does not start. RAUC, an update system for embedded Linux, does that work. The OS Agent, a small program on the host, does host tasks for the Supervisor, like moving the data disk.
• The Supervisor is a Python program that runs in a container on top of it. It runs Home Assistant Core, apps, and its own plugins, makes backups, installs updates, and keeps an eye on the health of the system.

This area is for developers who want to work on either one. For the OS, you are working with embedded Linux: Buildroot, kernels, bootloaders, and board support. For the Supervisor, you are working with async Python, Docker, and D-Bus, the message bus that Linux services use to talk to each other. Neither needs you to know the other.

Run by the Supervisor, each in its own container

• Home Assistant CoreHome Assistant itself
• AppsSoftware next to Core
• PluginsDNS, audio, CLI, and more

Manages everything above, in a container of its own

• SupervisorRuns, updates, and backs up it all

Home Assistant OS

• DockerRuns the containers
• NetworkManagerNetworking
• RAUCUpdates, with two system slots
• OS AgentHost tasks for the Supervisor
• BuildrootBuilt from source, read-only

Boards

• Green and YellowHome Assistant hardware
• Raspberry PiPi 3, 4, and 5
• ODROIDHardkernel boards
• PCGeneric x86-64 and aarch64
• Virtual machineOVA, QCOW2, and more

The architecture area explains the big picture. This area goes into the details you need to change things.

• Your first contribution: run the Supervisor in its development container, make a change, and open a pull request.
• Installation types: where the OS and the Supervisor are used, and where they are not.

• Overview: what is in the OS, how it boots, and how the repository is organized.
• Build an image: set up the build container and build for a board.
• Test your build: boot it in QEMU, run the tests, and install it on a device.
• Configure the host: the CONFIG USB drive, kernel modules, udev rules, and time servers.
• Configure networking: NetworkManager connections, Wi-Fi, and static addresses.
• Debug the host: SSH on port 22222, the serial console, and logs.
• Releases and builds: branches, version numbers, and the build pipelines.
• Reference: partitions, the update system, board metadata, and supported boards.

• Overview: what the Supervisor does, and what it runs.
• Set up a development environment: run the Supervisor in a development container, and test on a real system.
• Debug the Supervisor: attach a Python debugger and read the logs.
• Connect Core to a Supervisor: work on the hassio integration against a real Supervisor.
• How it works: architecture, jobs, the resolution center, and plugins.

The Supervisor is also what runs apps. Building apps, and the Supervisor API reference they use, live in the Apps area.

• The #operating-system channel on the Home Assistant Discord is the place for questions about Home Assistant OS and the Supervisor. Can't see the channel? Under Channels & Roles, choose I want to contribute dev skills to Home Assistant.
• Issues and pull requests live in home-assistant/operating-system and home-assistant/supervisor. The plugins each have their own repository, listed on the plugins page.
• Adding support for a new board is an architecture decision. Read ADR-0015 and ADR-0017, and start a discussion in the architecture repository before you write code.