Home Assistant Node-RED Guide: Visual Automations Made Easy

Home Assistant's built-in automation editor handles most everyday tasks, but when you need multi-step logic — conditional delays, parallel branches, or flows that react to several entities at once — it quickly becomes unwieldy. Node-RED is the visual, flow-based programming tool that fills that gap. It runs as a lightweight add-on inside Home Assistant and connects to every entity, service, and event on your system.

What Is Node-RED?

Node-RED is an open-source, browser-based flow editor originally developed by IBM and now maintained by the OpenJS Foundation. You wire together nodes — each representing an input, logic step, or output — to build event-driven automations without writing traditional code. A flow that would take thirty lines of YAML in Home Assistant's automation editor can often be drawn in under a minute in Node-RED.

For Home Assistant users, the key package is node-red-contrib-home-assistant-websocket, which adds a full set of HA-specific nodes: state listeners, service callers, entity readers, and event firers. This integration communicates over the Home Assistant WebSocket API, so it stays in sync in real time.

Installing Node-RED as a Home Assistant Add-on

The easiest way to run Node-RED alongside Home Assistant is via the official Supervisor add-on store. This method keeps everything in one place and handles start-up automatically.

1. In Home Assistant, go to Settings → Add-ons → Add-on Store.
2. Search for Node-RED and select the community add-on maintained by the Home Assistant community.
3. Click Install. The add-on pulls the Node-RED image and the node-red-contrib-home-assistant-websocket package automatically.
4. Once installed, enable Start on boot and Watchdog, then click Start.
5. Open the web UI — Node-RED runs on port 1880 by default. You can access it via the Open Web UI button or at http://<your-ha-ip>:1880.

If your Home Assistant instance uses SSL, ensure you've configured the add-on's SSL settings accordingly, or access it via the Ingress link inside the HA UI, which handles authentication for you.

Understanding the Key Nodes

Once inside the Node-RED editor, you'll see a palette on the left. The Home Assistant section contains the nodes you'll use most often:

events: state

Triggers a flow whenever a specified entity changes state. You can filter by new state, old state, or both. This is the equivalent of a Home Assistant state trigger.

current state

Reads the current state of an entity on demand, rather than waiting for a change. Useful for checking whether a light is already on before deciding what to do next.

call service

Calls any Home Assistant service — turning a light on, locking a door, sending a notification. You specify the domain, service, entity ID, and any service data in the node's configuration.

fire event

Fires a custom event on the Home Assistant event bus. Other automations, scripts, or Node-RED flows can listen for this event and react accordingly.

Standard Node-RED nodes — delay, switch, change, function — slot in between HA nodes to add timing, branching, and data manipulation that the native automation editor doesn't support cleanly.

Building Your First Flow: Motion Sensor → Delayed Light Off

This classic flow solves a common problem: turn a light on when motion is detected, then turn it off — but only if no motion has been detected again during the delay period. In Home Assistant's YAML automations this requires a complex restart-mode configuration; in Node-RED it's a handful of nodes.

[events: state] → [switch: motion on/off?]
                      ↓ on              ↓ off
               [call service:      [delay: 2 min]
               light.turn_on]           ↓
                              [current state: still clear?]
                                           ↓ yes
                                    [call service:
                                     light.turn_off]

Here's how to wire it up:

1. Drag an events: state node onto the canvas. Set the entity to your motion sensor (e.g. binary_sensor.hallway_motion).
2. Add a switch node. Route messages where msg.payload equals "on" to one output and "off" to another.
3. Wire the on output to a call service node set to light.turn_on for your target light.
4. Wire the off output to a delay node set to 2 minutes. Enable "Reset delay if a new message arrives" — this restarts the timer if motion is detected again before it expires.
5. After the delay, add a current state node for the motion sensor, then a switch that checks whether the state is still "off".
6. If clear, wire to a call service node set to light.turn_off.

Deploy the flow using the red Deploy button in the top-right corner. The flow activates immediately — no restart needed.

Exporting and Sharing Flows

Node-RED flows are stored as JSON, which makes them easy to back up and share. Go to the hamburger menu → Export → Clipboard to copy the flow JSON. You can paste it into the flows.nodered.org community library or share it directly with other users.

For disaster recovery, the Node-RED add-on stores flow data in /config/node-red/ inside your Home Assistant configuration directory, so it's included in your Home Assistant backups.

Node-RED vs Home Assistant Automations

Node-RED isn't a replacement for the native automation editor — it's a complement to it. Use the native editor for simple, single-trigger automations (e.g. "turn on the porch light at sunset"). Switch to Node-RED when you need:

• Multi-step conditional logic with parallel branches
• Timers that reset on new events (like the motion flow above)
• Data transformation — e.g. converting a sensor reading before logging it
• Integrations with external APIs — Node-RED's library has thousands of community nodes
• Visual debugging — the debug sidebar shows live message payloads as flows run

If you're building out a more advanced setup, Node-RED pairs well with Home Assistant's MQTT integration, letting you subscribe to and publish MQTT topics directly inside your flows.

Tips for a Reliable Setup

Use named connections. The websocket integration node appears as a global config node. Give it a clear name and reuse it across all your HA nodes rather than creating duplicates.

Enable Watchdog. The add-on's Watchdog setting restarts Node-RED automatically if it crashes — essential for production automations.

Version your flows. Export flows to your Home Assistant backup routine. Consider storing the JSON in a Git repository alongside your HA configuration for change tracking.

Keep flows modular. Break large automations into smaller, linked flows using link in and link out nodes. This makes debugging far easier and lets you reuse logic across multiple flows.

For more on structuring complex automations, see our Home Assistant automations guide.

Related: Home Assistant MQTT broker setup, Home Assistant blueprints guide, and Home Assistant presence detection.