hass-node-red: a Home Assistant companion for driving Node-RED flows

A companion, not a replacement

This repository is the Node-RED Companion Integration, and the word companion is the important one. It is described as a companion component to node-red-contrib-home-assistant-websocket for tighter integration of Node-RED with Home Assistant, and the two are separate projects by the same author. The websocket contrib is the part that lets Node-RED talk to Home Assistant over the websocket API, which is how a flow reads entity states and calls services. This component fills in the other direction. The overview describes it as bridging Node-RED and Home Assistant, allowing you to manage Home Assistant entities and automations directly from Node-RED, so you can create and update entities from a flow, and from the Home Assistant side you can enable or disable Node-RED flows. The name Node-RED Companion Integration is what you search for in the Home Assistant interface, and the domain used in the setup links is nodered. The project is MIT licensed, its primary language is Python, and the repository carries a HACS badge, which marks it as a default repository in the Home Assistant Community Store, so it can be installed without copying files by hand.

What the component can actually create and control

The key features are listed in four groups, and the first one is the largest. Entity management means creating and updating Home Assistant entities from Node-RED, and the list of entity types is specific: binary sensors, buttons, numbers, selects, sensors, switches and text fields. That list matters, because it maps onto the entity types that Home Assistant's own UI can create, so a flow can produce a helper entity that then appears in dashboards and can trigger automations like any other. The second group is flow control, enabling or disabling Node-RED flows directly from the Home Assistant user interface, which is the feature with the most obvious appeal and also the one with the most caution, since it means a dashboard button can stop or start a running flow. The third is webhooks, creating and managing Home Assistant webhooks with the handling done in Node-RED, which is a way to let an external event reach a flow without going through an entity. The fourth is device automation, using device triggers and actions within Node-RED for advanced automation capabilities, which is a different mechanism from entity-level triggers and reaches features that only exist at the device level, such as the button on a physical device.

Installing through HACS, then adding the device

The HACS route is the documented default, and the steps are worth following exactly because the second half of the setup is what people trip over. You navigate to the integration inside the Home Assistant Community Store, and the manual instructions are to search for hass-node-red in HACS and click the result. Then you click the blue Download button at the bottom right, click Download again in the version selection popup to get the latest version, and restart Home Assistant. The restart produces a clickable repair item in Settings, which is the signal that the integration installed correctly. Installing the device is a separate step from installing the integration. You go to Settings in the Home Assistant sidebar, select Devices and Services, click the blue + Add Integration button at the bottom right, search for Node-RED Companion, and click it, then follow the on-screen prompts. The distinction between the two steps is the thing to remember, because the file is present in the configuration directory but nothing works until a device entry has been created for it. The manual installation path exists for anyone who cannot use HACS. You locate the Home Assistant configuration directory, the one holding configuration.yaml, create a custom_components directory if it does not exist, create a folder named nodered inside it, download all files from the custom_components/nodered/ directory in this repository, place them in the new nodered directory, restart Home Assistant, refresh the browser, and then add the integration from Devices and Services as before.

Configuration happens in Node-RED, not in Home Assistant

The configuration section is a single sentence, and it is a meaningful design decision rather than an omission. Once the Node-RED Companion Integration is installed and added via Home Assistant Integrations, all further configuration is managed from within Node-RED. So the integration acts as a bridge that Home Assistant calls into, and the settings that govern how it behaves live on the Node-RED side where the flows live. For a user with many flows this keeps the operational surface in one place, and it also means the Home Assistant side of the setup stays as small as the config flow. The dependency direction is the other way round from what you might expect, since the websocket contrib is what the companion talks to, and the minimum requirements are explicit about the versions. The companion needs node-red-contrib-home-assistant-websocket at v0.57 or newer, and Home Assistant at 2024.5 or newer. The websocket version floor is the more subtle of the two, because a mismatch there shows up as a feature that quietly does nothing rather than as an error at startup, so it is the one to check first when something is not working.

The repository is a standard custom component, packaged properly

The top level of the repository shows what a well-formed Home Assistant custom component looks like, and the packaging details are the interesting part. There is a custom_components/ directory holding the actual integration code, a config/ directory which is the Home Assistant test fixture configuration, a tests/ directory, and the hacs.json file that declares the component to the HACS store along with an info.md description page. There is a .devcontainer/ directory, so the project can be worked on in a container, and a .pre-commit-config.yaml, a .ruff.toml for the Python linter, a .prettierignore, a pytest.ini and separate requirements.txt and requirements_test.txt files, so the test dependencies are kept apart from the runtime ones. The runtime requirements are small and readable, with colorlog at 6.12.0 pinned exactly, homeassistant listed without a version bound, pre-commit and hassil. The unpinned homeassistant entry is normal for a custom component, since the component is expected to run inside a Home Assistant installation and follows the core version of the host. The release process is automated through release-please, with a .release-please-manifest.json and a release-please-config.json, so the changelog and the version tags are generated rather than maintained by hand.

Where hass-node-red is the wrong tool

The first limit is that it is one half of a pair, and if your setup already runs the websocket contrib you may not need it at all. The websocket contrib alone gives Node-RED access to Home Assistant entities and services, which covers the most common direction of travel, and this component adds the reverse direction plus the flow control. Installing it without the specific use case in mind gives you a custom component, a device entry and a restart for features you never call. The second limit is the risk of a custom component, which is that it is not covered by the same upgrade testing as a core integration, and Home Assistant core can change its internal APIs between releases even when the public integration API is stable. The version floors tell you the project is careful about this, but they also tell you the floors move, and every floor that moves is a version you must re-test. The third is the flow control feature, and this is a design question rather than a bug. Letting a Home Assistant entity or dashboard button enable and disable a running Node-RED flow is powerful, and it also means a mistake in an automation, a mis-tapped button or a badly written script can stop a flow that is doing something important, with the only sign being that the automation quietly stops. A dry run or an explicit status entity would be a safer pattern, and the README does not describe one. The fourth is that all of this presumes you run both systems, and a small Home Assistant instance with a handful of YAML automations needs none of it.

Editorial conclusion

Adopt hass-node-red if you already run both Node-RED and Home Assistant and want the two to be able to create and control things in each other, in particular if you want to enable or disable Node-RED flows from a Home Assistant dashboard. Skip it if you only need one direction of the integration, since the websocket contrib already covers the other way, and note that it is a custom component rather than a core integration, so it carries the upgrade risk that implies. Verify first that your websocket contrib is at version 0.57 or newer and your Home Assistant is 2024.5 or newer, and that you understand that flow enable and disable is a live switch on running flows rather than a dry run.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zachowj/hass-node-red on GitHub