Home Assistant Supervisor: Container Orchestration Layer
/supervisor
Home Assistant Supervisor is the container-based system that runs and manages a Home Assistant Core installation, handling network settings and software updates through an API that Home Assistant itself calls rather than one you touch directly. Reach for it when you want Home Assistant to manage its own containers and updates instead of scripting that yourself; skip this repo unless you're developing against its API or filing an RFC.
What is Home Assistant Supervisor?
Home Assistant Supervisor is the container-based system behind Home Assistant (formerly called Hass.io), managing a user's Home Assistant Core install and the applications that run beside it. Home Assistant talks to the Supervisor, which exposes an API for changing network settings and installing or updating software, so the two operate as a paired frontend and backend manager rather than a single app.
Simplifying Private Cloud Home Automation
Running a home automation platform usually means someone has to manually manage the OS, container runtime, network config, and update process for every piece of software touching it. Home Assistant Supervisor exists to take that operational burden off the user: its README frames Home Assistant as a 'private cloud' for home automation, and the Supervisor is the piece that actually manages the containers, network settings, and update flow so Home Assistant Core and its surrounding software don't need separate manual upkeep.
Core Management Capabilities
- โContainer-based management of a Home Assistant Core installation and the applications running alongside it, per the README description of the project.
- โA system API that Home Assistant itself calls to control the install, rather than a UI you drive directly.
- โNetwork settings can be changed through that API rather than by hand-editing config on the host.
- โInstalling and updating software runs through the same API path, so Home Assistant Core and its Supervisor stay in sync.
- โA three-stage release pipeline: PRs land on main, builds move to the dev channel, then to beta, and finally to stable once the stable.json file is updated.
- โTagged as an orchestrator project in Python, built specifically around Docker.
Getting Started with Installation
This repo's own README doesn't walk through installation steps. It points to https://home-assistant.io/getting-started as the place to actually install Home Assistant. There's no docker run command, package name, or config file documented in this repository's README itself, so treat that external getting-started page as the real starting point rather than anything in this repo.
Strengths
- โUpdate path is structured: three distinct channels (dev, beta, stable) gated by an explicit stable.json update step, so testers can track builds before general release.
- โAPI-driven management means Home Assistant Core doesn't need manual container or network babysitting; the Supervisor handles it through the API, per the README.
- โApache-2.0 license, permissive, with no proprietary lock-in language in the README.
- โClear contribution path: minor fixes can go straight to a PR, only larger changes need an RFC first, so the bar for small contributions is low.
- โTagged 'hacktoberfest' alongside 'docker' and 'orchestrator' on GitHub, which points to an actively maintained project.
Potential Considerations
- โณThe README is thin on specifics: no version number, roadmap, or list of supported platforms/architectures appears in the facts available here.
- โณInstall steps aren't documented in this repo; you're sent to an external getting-started page instead of anything self-contained here.
- โณDay-to-day usage, such as CLI commands or example API calls, isn't documented in the README either; you're expected to interact with Home Assistant, not the Supervisor directly.
- โณSignificant changes require an RFC before a pull request, which is an extra process step compared with a repo that accepts any PR directly.
- โณThe README gives no adoption numbers or benchmark data beyond the repo's own star and fork counts, so claims about real-world scale rest on those two figures alone.
Other Home Automation Platforms
Frequently Asked Questions
Home Assistant Supervisor manages a Home Assistant Core installation and the software around it: it handles network settings and installs or updates software through an API that Home Assistant itself calls.
Home Assistant communicates with the Supervisor rather than the other way around: Home Assistant calls the Supervisor's API to manage the underlying Home Assistant Core installation, including network settings and software updates.
The Home Assistant Supervisor README doesn't include install steps itself; it points to https://home-assistant.io/getting-started as the place to install Home Assistant.
Home Assistant Supervisor is licensed under Apache-2.0, according to its GitHub repository.
Small changes and bugfixes can go straight to a pull request against Home Assistant Supervisor, but the README asks contributors to open an RFC first for significant changes, with development instructions linked separately.
Best use cases
- โขRunning a Home Assistant install where the platform manages its own containers and updates automatically instead of a manually maintained container-based Home Assistant Core setup.
- โขContributing to Home Assistant's install and update infrastructure, following the RFC-based process the README describes for significant changes.
- โขTracking builds through the dev and beta channels before they reach stable, if you want to test changes early.
- โขStudying how Home Assistant splits responsibility between Core and Supervisor as a reference for API-driven system management.
How to use
Day-to-day usage of Home Assistant Supervisor isn't spelled out in its own README; there's no CLI reference or example API call in the facts available here. What the README does describe is the release flow you'd follow if you're working on the Supervisor itself: pull requests land on main, a build moves to the dev channel, then to beta, and only after the stable.json file is updated does that build become the stable release. The Supervisor isn't something you call directly. Home Assistant's own interface is what talks to it.
Who should try it โ and who should skip
Try digging into Home Assistant Supervisor if you're contributing to Home Assistant's install and update infrastructure, want to track builds through the dev and beta channels before they hit stable, or need to understand how Home Assistant Core talks to its own management API. Skip it if you're a regular Home Assistant user: you'll interact with Home Assistant's interface, not this repo, and the README doesn't position it as something end users install or run standalone.
Related repositories
Is supervisor worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of supervisor.