# OS and Supervisor > Work on Home Assistant OS and the Supervisor, the two pieces that turn a board or a virtual machine into a Home Assistant system that runs, updates, and repairs itself. Source: https://contributors.home-assistant.io/os/ Most people run Home Assistant on [Home Assistant OS](https://contributors.home-assistant.io/glossary/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. ## How the pieces fit Diagram. From top to bottom: what runs on what. Select a box to read more about it. - Run by the Supervisor, each in its own container - [Home Assistant Core](https://contributors.home-assistant.io/core/): Home Assistant itself - [Apps](https://contributors.home-assistant.io/apps/how-apps-work/): Software next to Core - [Plugins](https://contributors.home-assistant.io/os/supervisor/plugins/): DNS, audio, CLI, and more - Manages everything above, in a container of its own - [Supervisor](https://contributors.home-assistant.io/os/supervisor/architecture/): Runs, updates, and backs up it all - [Home Assistant OS](https://contributors.home-assistant.io/os/operating-system/) (the subject of this page) - Docker: Runs the containers - [NetworkManager](https://contributors.home-assistant.io/os/operating-system/networking/): Networking - [RAUC](https://contributors.home-assistant.io/os/operating-system/update-system/): Updates, with two system slots - OS Agent: Host tasks for the Supervisor - [Buildroot](https://contributors.home-assistant.io/os/operating-system/build/): Built from source, read-only - [Boards](https://contributors.home-assistant.io/os/operating-system/boards/) - [Green and Yellow](https://contributors.home-assistant.io/os/operating-system/boards/): Home Assistant hardware - [Raspberry Pi](https://contributors.home-assistant.io/os/operating-system/raspberry-pi/): Pi 3, 4, and 5 - [ODROID](https://contributors.home-assistant.io/os/operating-system/odroid/): Hardkernel boards - [PC](https://contributors.home-assistant.io/os/operating-system/generic/): Generic x86-64 and aarch64 - [Virtual machine](https://contributors.home-assistant.io/os/operating-system/virtual-machine/): OVA, QCOW2, and more The [architecture](https://contributors.home-assistant.io/architecture/platform/) area explains the big picture. This area goes into the details you need to change things. ## Start here - [Your first contribution](https://contributors.home-assistant.io/os/first-contribution/): run the Supervisor in its development container, make a change, and open a pull request. - [Installation types](https://contributors.home-assistant.io/os/installation-types/): where the OS and the Supervisor are used, and where they are not. ## Home Assistant OS - [Overview](https://contributors.home-assistant.io/os/operating-system/): what is in the OS, how it boots, and how the repository is organized. - [Build an image](https://contributors.home-assistant.io/os/operating-system/build/): set up the build container and build for a board. - [Test your build](https://contributors.home-assistant.io/os/operating-system/test/): boot it in QEMU, run the tests, and install it on a device. - [Configure the host](https://contributors.home-assistant.io/os/operating-system/configuration/): the `CONFIG` USB drive, kernel modules, udev rules, and time servers. - [Configure networking](https://contributors.home-assistant.io/os/operating-system/networking/): NetworkManager connections, Wi-Fi, and static addresses. - [Debug the host](https://contributors.home-assistant.io/os/operating-system/debugging/): SSH on port 22222, the serial console, and logs. - [Releases and builds](https://contributors.home-assistant.io/os/operating-system/releases/): branches, version numbers, and the build pipelines. - Reference: [partitions](https://contributors.home-assistant.io/os/operating-system/partitions/), [the update system](https://contributors.home-assistant.io/os/operating-system/update-system/), [board metadata](https://contributors.home-assistant.io/os/operating-system/board-metadata/), and [supported boards](https://contributors.home-assistant.io/os/operating-system/boards/). ## Supervisor - [Overview](https://contributors.home-assistant.io/os/supervisor/): what the Supervisor does, and what it runs. - [Set up a development environment](https://contributors.home-assistant.io/os/supervisor/development/): run the Supervisor in a development container, and test on a real system. - [Debug the Supervisor](https://contributors.home-assistant.io/os/supervisor/debugging/): attach a Python debugger and read the logs. - [Connect Core to a Supervisor](https://contributors.home-assistant.io/os/supervisor/core-connection/): work on the `hassio` integration against a real Supervisor. - How it works: [architecture](https://contributors.home-assistant.io/os/supervisor/architecture/), [jobs](https://contributors.home-assistant.io/os/supervisor/jobs/), [the resolution center](https://contributors.home-assistant.io/os/supervisor/resolution-center/), and [plugins](https://contributors.home-assistant.io/os/supervisor/plugins/). The Supervisor is also what runs [apps](https://contributors.home-assistant.io/glossary/app/). Building apps, and the Supervisor API reference they use, live in the [Apps](https://contributors.home-assistant.io/apps/) area. ## Who to talk to - The [**#operating-system**](https://discord.com/channels/330944238910963714/1475552965954900018) channel on the [Home Assistant Discord](https://www.home-assistant.io/join-chat/) 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](https://github.com/home-assistant/operating-system) and [home-assistant/supervisor](https://github.com/home-assistant/supervisor). The plugins each have their own repository, listed on the [plugins](https://contributors.home-assistant.io/os/supervisor/plugins/) page. - Adding support for a new board is an architecture decision. Read [ADR-0015](https://github.com/home-assistant/architecture/blob/master/adr/0015-home-assistant-os.md) and [ADR-0017](https://github.com/home-assistant/architecture/blob/master/adr/0017-hardware-screening-os.md), and start a discussion in the [architecture repository](https://github.com/home-assistant/architecture) before you write code.