whatisgithub

What is operating-system?

home-assistant/operating-system — explained in plain English

Analysis updated 2026-06-22

7,097PythonAudience · ops devopsComplexity · 5/5Setup · hard

In one sentence

A minimal Linux OS built from scratch using Buildroot specifically to run Home Assistant smart home software on Raspberry Pi, ODROID, and x86 computers, with Docker-based isolation and over-the-air updates.

Mindmap

mindmap
  root((repo))
    What it does
      Minimal Linux OS
      Runs Home Assistant
      OTA updates
    Tech Stack
      Buildroot toolchain
      Docker containers
      AppArmor security
    Supported hardware
      Raspberry Pi
      ODROID boards
      x86-64 UEFI
    Audience
      OS contributors
      Embedded developers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Build a custom Home Assistant OS image from source for a Raspberry Pi or ODROID single-board computer

USE CASE 2

Contribute kernel patches or security modules to the minimal Linux system that runs Home Assistant

USE CASE 3

Set up a dedicated smart home server on a spare x86 PC that receives updates without a USB drive

USE CASE 4

Study how Buildroot compiles a production Linux OS from scratch for embedded or appliance-style deployments

What is it built with?

PythonBuildrootDockerLinuxAppArmor

How does it compare?

home-assistant/operating-systemdatawhalechina/fun-rectraceloop/openllmetry
Stars7,0977,0977,100
LanguagePythonPythonPython
Setup difficultyhardhardmoderate
Complexity5/54/52/5
Audienceops devopsresearcherdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1day+

Building from source via Buildroot requires a Linux host, significant compile time, and a full cross-compilation toolchain.

So what is it?

Home Assistant Operating System is a minimal Linux-based operating system built specifically to run Home Assistant, the popular open-source home automation platform. Rather than installing Home Assistant on top of a general-purpose operating system like Ubuntu, this is a stripped-down OS designed from scratch around a single purpose: hosting Home Assistant and its companion apps as efficiently as possible. It runs on small single-board computers like the Raspberry Pi and ODROID, as well as on standard x86-64 computers with a UEFI motherboard. Because it is not built on a conventional Linux distribution, it leaves out everything that is not needed for the job, keeping memory usage low and disk activity minimal. Updates can arrive over the air without plugging in a USB drive, though offline updates via USB are also supported. Under the hood, it uses Docker to run Home Assistant's components in separate containers. There is a piece called the Home Assistant Supervisor that manages those containers, handling updates, backups, and app installations through the Home Assistant web interface. This architecture keeps different parts of the system isolated from each other so one misbehaving add-on does not affect the rest. The OS is built using a tool called Buildroot, which compiles a Linux system from source rather than packaging an existing distribution. This approach gives the developers precise control over what ends up on the device. Security hardening is included through a Linux kernel security module called AppArmor, which limits what running processes are allowed to do. This repository is for people who want to contribute to or build the operating system itself. Ordinary users who just want to run Home Assistant on their device should follow the official installation guide on the Home Assistant website, which handles downloading and flashing the image without needing any of this source code.

Copy-paste prompts

Prompt 1
I want to compile Home Assistant Operating System from source for a Raspberry Pi 4. What does the Buildroot build process look like and what dependencies do I need on my host machine?
Prompt 2
How does Home Assistant OS use Docker to isolate the Supervisor container from the Home Assistant core and add-on containers?
Prompt 3
I want to add a custom AppArmor profile to a Home Assistant OS build. Show me how the existing profiles are structured and where to add a new one.
Prompt 4
What is the minimal set of changes I need to make to port Home Assistant OS to a new ARM single-board computer that is not currently supported?

Frequently asked questions

What is operating-system?

A minimal Linux OS built from scratch using Buildroot specifically to run Home Assistant smart home software on Raspberry Pi, ODROID, and x86 computers, with Docker-based isolation and over-the-air updates.

What language is operating-system written in?

Mainly Python. The stack also includes Python, Buildroot, Docker.

How hard is operating-system to set up?

Setup difficulty is rated hard, with roughly 1day+ to a first successful run.

Who is operating-system for?

Mainly ops devops.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.