📺 Rather watch a video version of this blog? Click here to view the video on my YouTube channel.
I opened an architecture proposal to rename "add-ons" to "apps" in Home Assistant. Before you think this is just bike-shedding about terminology, let me explain why this seemingly small change actually matters.
The confusion problem
Here's something I keep noticing. New users start using Home Assistant and when they want to add something for the first time, they often end up trying to add add-ons because it sounds like something that adds to Home Assistant. And while that's true, it's often not what they're looking for. They're actually looking for integrations.
This signals something important: the name doesn't really tell you what it is and what you need.
When you're new to Home Assistant, you open the interface for the first time with a light bulb you want to add. You see add-ons and integrations in the settings. Add-on sounds pretty much like the thing you want, right? You want to add something. Sounds logical. The names really don't tell you what they actually do.
Add-ons are software applications that run alongside Home Assistant. They're not Home Assistant itself. They run next to it. You can start them up and use them, and they can provide additional services to Home Assistant. Good examples include AdGuard Home, ESPHome, and MQTT Mosquitto.
Integrations integrate a device or service into Home Assistant. If you have a light bulb, you integrate that with Home Assistant and you get capabilities to control and monitor it through automations, dashboards, and so on.
So that's the difference. One is integrating something into Home Assistant, while add-ons run software alongside Home Assistant.
The AdGuard example makes it even more confusing
The two can connect to each other, and this makes it even more confusing. Take AdGuard Home, for example. You can find AdGuard Home in both the add-on store and in the integrations list.
That's because Home Assistant can run AdGuard alongside itself as the actual ad filtering system for your house. But Home Assistant can also integrate with that add-on you're running to get statistics from it, automate with it, and control it.
So there are two parts to AdGuard Home: the integration and the add-on. It's super confusing for new people.
The solution: apps
Let's just rename add-ons to apps. Because that feels way more natural. They're software applications running alongside Home Assistant. It's just more clear in terms of a mental model.
Apps run. You install apps onto something and you run them. Put yourself in the shoes of a user that just starts. I think it makes more sense that you integrate something and you can run apps too.
Think about your phone. You install apps on it. You know exactly what that means. An app is something that you run, you start it up, you do something with it. Your phone has a runtime capability of starting up those apps. Add-ons are kind of the same. They're different pieces of software that run on them.
So AdGuard has an app, ESPHome has an app, and they just run alongside Home Assistant.
Does this name change solve all the problems we can think off? No. A big step forward? Yes!
No functional changes
The proposal is very clear: it doesn't change a bit. It only renames it. Nothing is breaking. We're literally just changing the label in the UI. Call it apps everywhere, and Bob's your uncle.
The alternatives we considered
In the GitHub discussion, we've been discussing alternatives, and I think it's fair to list them out here.
Widgets came up, but I don't think that makes sense. A widget feels more like a UI element, not something that would be a software application running alongside Home Assistant. I actually think widgets would be something we should consider using in the future for dashboards. Dashboards full of widgets makes sense. But it's out of scope for this one.
Extensions also came up, a little bit like Google Chrome has. But I would argue that browser extensions are more like add-ons in the traditional sense. They extend functionality. They're more like our integrations, basically. Not suitable.
Containers is technically accurate. Under the hood, add-ons are Docker containers managed by Home Assistant with specific APIs. There's a little bit of layering on top of them and between them. In their essential form, they are containers.
However, if I think about my dad starting to use Home Assistant, telling him "hey, you can install more containers on this thing," I don't think that will fly. Containers is too technical for most users.
Why this matters: the Discord story
This is about reducing frustration for newcomers. When someone installs Home Assistant and immediately gets confused and frustrated about terminology, that's not good.
Here's how bad this confusion has gotten: a few months ago on Discord, we actually gave up on having separate channels for add-ons and integrations. We just merged them and slapped them together because people didn't really understand the difference. That's really problematic. That is something we need to fix.
And that's what this proposal is about.
Your input matters
This is still an open discussion. The architecture proposal is discussion #1287 on GitHub, and I'd love to hear your thoughts.
Do you think "apps" works? Should we keep "add-ons"? Is there a better alternative? Jump into the conversation and let's figure out the best path forward together.
../Frenck
I also recorded a vlog about this proposal on my way to GitHub Universe 2025. You can watch it here if you prefer video format. Fair warning: it's my first vlog, so there's a bit of awkwardness as I share my thoughts this way!
