home-assistant-config: Open Source Automation

What is home-assistant-config?

What it is

home-assistant-config is a public repository containing the personal Home Assistant configuration of Franck Nijhof, the lead of the Home Assistant project. It lives in the Home Assistant ecosystem, an open-source smart-home platform that runs locally on hardware such as a Raspberry Pi and connects to over 2,000 devices and services without relying on cloud services.

The repository solves a concrete organization problem for Home Assistant users. It shows how to structure a growing installation without a single large configuration.yaml file. The configuration uses Home Assistant packages, so each integration has its own YAML file under the integrations directory, while automations, scripts, scenes, blueprints, and ESPHome device definitions are split into separate directories.

Key capabilities

The repository uses a modular configuration pattern, where each integration lives in its own YAML file under the integrations directory and is loaded through Home Assistant packages.
The configuration is validated daily against the stable, beta, and dev versions of Home Assistant Core.
The repository includes a dedicated ESPHome directory and a CI workflow for ESPHome device configurations.
The repository runs yamllint, remarklint, Prettier, actionlint, and zizmor on every commit.
Automations, scripts, and scenes are stored in separate directories, which makes the setup easier to manage as it grows.
A blueprints directory contains automation and script blueprints.
The repository separates real secrets from test secrets, with secrets.yaml excluded and secrets.fake.yaml used for CI testing.

Who uses it and how

Home Assistant users browse the repository as a reference configuration for modular YAML organization.
Self-hosters adapt the packages pattern to split their own integrations, automations, scripts, and scenes into separate files.
Contributors can propose improvements because the repository has contribution guidelines and is treated as an active open-source project.
ESPHome users inspect the ESPHome directory for device configuration examples and CI workflow patterns.
CI maintainers can reuse the linting and testing approach for validating Home Assistant configuration changes.

Getting started

Use the repository as a Home Assistant configuration reference by loading the minimal configuration.yaml file, placing integration files in the integrations directory, and supplying a local secrets.yaml file that is not committed. The README also indicates that ESPHome files live in the esphome directory and that CI testing uses secrets.fake.yaml.

When to use it — and when not to

Use this repository when you want an example of a modular, tested, and linted Home Assistant configuration, especially if you prefer separate files over a large configuration.yaml file. It is not a turnkey product, because it is a personal setup and requires you to run Home Assistant yourself, manage YAML files, and provide your own secrets. The main trade-off is that users must understand Home Assistant packages, integrations, and CI workflows before adapting it to their own environment.

project readme (upstream, from github) — read inline

Frenck's Home Assistant Configuration

Project Maintenance

What is Home Assistant?

Not familiar with Home Assistant? Oh, you're in for a treat! :wink: It's an open source smart home platform that runs locally on, for example, a Raspberry Pi. It connects to over 2,000 different devices and services, from lights and sensors to media players and EVs, all without relying on some cloud. It's one of the most active open source projects on GitHub and is backed by the Open Home Foundation.

About

Hey! :wave: This is my personal Home Assistant configuration. I'm Frenck, the lead of the Home Assistant project and Chair of the Leader Committee at the Open Home Foundation.

I like to keep things tidy, so the whole configuration is modular using Home Assistant's packages pattern. Every integration gets its own file in the integrations/ directory. No giant configuration.yaml here :sweat_smile:

Feel free to poke around, steal ideas, or get inspired. Be sure to hit the :star2: if you find it useful!

Key Features

Fully modular. Each integration lives in its own YAML file under integrations/, loaded as packages. Clean, organized, easy to find stuff.
Tested every night. This config is validated daily against the stable, beta, and dev versions of Home Assistant Core. If something is going to break, I'll know before it hits a release :muscle:
ESPHome ready. Got a dedicated directory and CI workflow for ESPHome device configurations.
Linted to the bone. yamllint, remarklint, Prettier, actionlint, and zizmor all run on every commit. Yes, I take my YAML seriously.
Automations, scripts & scenes. All split into their own directories, making it easy to manage as things grow.

Repository Structure

.
├── configuration.yaml        # Minimal bootstrap, loads packages
├── integrations/             # Modular integration configs (packages)
├── automations/              # Split automation YAML files
├── scripts/                  # Split script YAML files
├── scenes/                   # Split scene YAML files
├── blueprints/               # Automation & script blueprints
├── esphome/                  # ESPHome device configurations
├── secrets.yaml              # Secrets (not in repo)
└── secrets.fake.yaml         # Fake secrets for CI testing

The configuration.yaml is intentionally minimal. It only loads the integrations/ directory as packages. Each integration gets its own file, keeping things clean and easy to navigate.

Contributing

I consider my personal Home Assistant configuration an active open-source project. So if you feel like adding an improvement, feel free to contribute.

We have set up a separate document containing our contribution guidelines.

Thank you for being involved! :heart_eyes:

Useful Links

Want to learn more or get involved? Here are some good starting points:

Authors & contributors

The original setup of this repository is by Franck Nijhof.

For a full list of all authors and contributors, check the contributor's page.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Frequently asked questions

Is home-assistant-config free to use?

home-assistant-config is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does home-assistant-config do?

:house: My Home Assistant configuration, a bit different that others :) Be sure to :star2: this repository for updates!

What is home-assistant-config written in?

home-assistant-config's source is publicly available at https://github.com/frenck/home-assistant-config, with 2,026 GitHub stars.