Node-RED

What it is: An open-source tool for "low-code" programming of event-driven applications. You build logic in the browser from nodes connected by wires, with messages (msg) flowing between them.1 In the smart home it mainly serves as a second automation engine next to Home Assistant: it talks to HA over the WebSocket API and also handles MQTT, HTTP and hundreds of other integrations from the palette.2 The current release is Node-RED 5.0.7 (09/2026), which requires Node.js 22.9+.1

Node-RED or HA automations?

Synthesis (unsourced, common community practice):

Situation Rather HA automation Rather Node-RED
Simple "when X, do Y" βœ“
Branching, waiting, timers, several conditions βœ“, the logic is visible in the graph
Working with data (JSON, HTTP APIs, transformations) βœ“
Integrations outside HA (MQTT, HTTP endpoints, DB) βœ“
Must work without an extra process βœ“

Node-RED is one more process to update, back up and secure (see below).

Core concepts

Node-RED flow anatomy
Flow, nodes, the msg message and context on a "light by the sun" example. Own diagram (Synthesis) based on Node-RED docs1 and2.

Editor

Node-RED 5 editor
The Node-RED 5 editor: Explorer (flows, subflows, config nodes) and the node Palette on the left, the workspace in the middle, Information and Debug messages on the right, Deploy at the top. Source: Node-RED docs1 (screenshot from the docs, 2026-06).

Connecting to Home Assistant

Node-RED and Home Assistant
How Node-RED and HA talk to each other. Own diagram (Synthesis) based on HA nodes docs2.

  1. Install the nodes node-red-contrib-home-assistant-websocket (Node.js 20+, Node-RED 3.1.1+, HA 2024.3+). The community HA Node-RED add-on has them preinstalled.2 In HA 2026 add-ons are called Apps (Settings > Apps).3
  2. Create a token: in your HA profile β†’ Create Token (long-lived access token). The user must be in the administrators group. A separate HA user for Node-RED is recommended so you can see what it changes.2
  3. Server config node: Base URL (e.g. http://<ha>:8123) and the token. With the add-on, just tick "I use the Home Assistant Add-on".2
  4. Verify the connection with an Events: all node (green "connected" status), then delete it for performance and use specific nodes.2

Most used nodes2:

First automation example2: Events: state on sun.sun with If State above_horizon. True output β†’ Action light.turn_off, false output β†’ Action light.turn_on. It matches the "Flow anatomy" diagram above.

HomeKit: node-red-contrib-homekit-bridged (NRCHKB)

The package through which Node-RED exposes devices to Apple Home (HomeKit) and lets you control them with Siri too.

Compatibility with Node-RED 5 / Node.js 24

The Node-RED 5.0.7 image (including the one on Umbrel) runs on Node.js 24. The stable NRCHKB 1.7.3 (01/2025) has no official Node.js 24 support; the issue is open. Version 2.0.0, meant for Node-RED 5, is still only a release candidate (2.0.0-dev.12) and has an open bug with Service nodes in subflows.4
Synthesis: as long as HomeKit works, don't update NRCHKB blindly. Before updating Node-RED or NRCHKB, back up /data and watch for the stable 2.0.0 release. Mind its breaking changes (no more custom mDNS, CameraControl).

Working with messages

// multiple outputs: return an array (null = nothing on that output)
if (msg.topic === "banana") {
    return [null, msg];
}
return [msg, null];

Example from Node-RED docs1.

Context and state

contextStorage: {
    default: { module: "localfilesystem" }
}

Installation

docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red

Security

The editor has no login by default. Anyone who reaches port 1880 can change and deploy flows.1

adminAuth: {
    type: "credentials",
    users: [{ username: "admin", password: "<bcrypt-hash>", permissions: "*" }]
}

Backups and versioning

Tips for structuring flows

Gotchas

Integrations

Related

Sources

  1. Node-RED Documentation + release notes β†— β€” official Node-RED documentation and release notes (version 5.0.7).
  2. node-red-contrib-home-assistant-websocket (documentation) β†— β€” documentation of the HA nodes (v0.81.0).
  3. Home Assistant Connect ZBT-2 (Nabu Casa Support) β†— β€” HA add-ons renamed to Apps.
  4. node-red-contrib-homekit-bridged (NRCHKB): README, npm, issues β†—
  5. umbrelOS / Umbrel Home (README, app store, product page) β†—