“Node-RED” is doing the work of four separate names

This guide pins four versions and treats them as four different things, because they are: the Home Assistant Community App that installs and runs the container, the Node-RED runtime that draws the editor and executes your flows, the HA WebSocket node package that talks to Home Assistant, and an optional dashboard that most installs never add. Calling all of it “Node-RED 22” is how people end up checking the wrong version, applying a setting to the wrong layer, or assuming that one layer's login protects a door it has never heard of.

The examples later in this guide build toward real automations — a hallway light such as light.living_room turning on when someone passes a motion sensor, a reminder sent when everyone leaves, a temperature check that fires a notification. The very first flow you build, in the next part, controls nothing. It produces a message and a line in Debug, and that is deliberate: you learn the runtime before you let it touch a device.

Four layers, four version numbers, and only one of them is optional

Every claim in this guide is checked against one specific commit of each project, not against whatever the main branch happens to look like today. That is what “pinned” means here, and it is why a screen that looks different on your install is worth a version check before it is worth a bug report.

flowchart TD
  A["Add-on 22.0.1
packages, Ingress, mounts, startup"] --> B["Node-RED 5.0.2
editor, runtime, Deploy, core nodes"]
  B --> C["HA WebSocket 0.80.3
server connection, events, Action node"]
  B -.-> D["FlowFuse Dashboard 2 1.30.2
optional, installed separately"]

The Add-on's pinned node-red/package.json lists exact dependencies, and what is on that list matters as much as what is not:

“Dashboard 2” in the package name identifies a product generation, not an instruction to pin some unrelated npm major version to 2. It is simply the name FlowFuse gives the current dashboard line.

Two thresholds that look like one, and who does what when a light should turn on

The Add-on manifest declares homeassistant: 2023.3.0. That is the number the Supervisor checks before it lets you install the Add-on at all — it is not the complete compatibility story. HA WebSocket 0.80.3's own README lists a separate, higher bar: Home Assistant 2024.3+, Node-RED 3.1.1+, and Node.js 18.2.0+. The bundled Node-RED 5.0.2 already clears its minimum, so the number worth holding onto is the Home Assistant one.

init: false is a container-manifest flag, not safe_mode. Do not fold the manifest's own install threshold, a README's user-facing prerequisite, and a container flag into one imagined “minimum Home Assistant version” — they answer three different questions, and only the middle one governs whether HA WebSocket behaves the way this guide describes.

Who does what when a light should turn on

Picture a motion sensor and a hallway light such as light.living_room, and an automation meant to turn the light on when someone walks through at night. Four layers touch that one event, and each has its own job:

• Home Assistant: the authority for what the sensor and the light actually are. Writing a name on the Node-RED canvas does not create a device.
• HA WebSocket 0.80.3: the bridge. It subscribes to state events, queries other entities, and asks Home Assistant to turn the light on through the Action node. Older documentation and older flows may still call this the Call Service node — this guide uses its current name, Action, throughout.
• Node-RED 5.0.2: the runtime that routes the message through nodes and wires and evaluates whatever conditions you built. Each msg is a JavaScript object, not one line of text — it can carry payload, topic, _msgid, and more.
• Add-on 22.0.1: the deployment package underneath all of it. It provides the data paths, the proxy, the permissions, and the preinstalled packages — and it has no opinion on whether your automation is a good idea.

A report that says only “the light didn't turn on” could point at any one of those four. Working out which layer is actually at fault, before you touch anything, is far faster than restarting the Add-on and hoping.

Edit, Deploy, and restart are three different reaches

Moving nodes around the canvas changes only what the editor is showing you. Clicking Deploy sends the scope you chose to the runtime, which is the first point any of it actually runs. Restarting the Add-on is a third, larger action again: it rebuilds the services around the runtime, not just the flows inside it. The official documentation tells you to restart the Add-on after changing its own configuration — that is a different act from Deploy, and it can affect timers, event subscriptions, and anything with an external side effect in a way a plain Deploy does not.

flowchart LR
  A["Move a node on the canvas.
Changes only the editor state"] --> B["Click Deploy.
Sends the chosen scope to the runtime"]
  B --> C["Restart the Add-on.
Rebuilds the services around the runtime"]

Authentication boundaries follow the same pattern of “looks like one thing, is actually several.” Home Assistant Ingress, a direct listener, the editor route, HTTP endpoints your own flows create, static content, and the optional dashboard each answer to a different check. Opening the editor safely from the Home Assistant sidebar does not mean every other door got the same lock. The rest of this part is that distinction, in detail.

Install, Start, check the log, then Open Web UI — in that order

The Add-on comes with a Home Assistant server connection already configured. The safest first move is not to paste in a YAML example from somewhere online; it is to follow the official sequence exactly once, with nothing added, and confirm each step before the next.

1. Step 1

   Open the Add-on page and confirm the name

   Use the Add-on details page to confirm you are installing Home Assistant Community App: Node-RED, not a separate Node-RED install on another host, and not a container image from an unfamiliar source.

2. Step 2

   Select Install, and add nothing else yet

   Wait for installation to finish before touching npm_packages, system_packages, or init_commands. 22.0.1 declares support only for aarch64 and amd64; there is no supported workaround for other hardware.

3. Step 3

   Start it, and let initialization finish untouched

   On first startup the Add-on creates what it needs under /config and runs its own migration for legacy data and themes. If /config/package.json already exists, it also tries to remove three conflicting legacy packages and logs a warning if it cannot. Do not edit files by hand while this is running.

4. Step 4

   Read the log before you decide anything failed

   The official sequence checks the log before declaring success. Look for a clean start or a specific error. Redact tokens, hostnames, URLs, and message payloads before you ever share a screenshot of it, and do not mash Start again just because the editor has not opened yet.

5. Step 5

   Select OPEN WEB UI

   The documentation is explicit that you do not need to add, change, or re-enter the server connection. Do not paste a token in just to feel like you finished a step.

6. Step 6

   Leave the default entry point alone, and write down what you saw

   Do not expose a direct port yet. Record the Add-on version and whether Ingress opened cleanly, then move on to the editor tour and the side-effect-free flow in the next part of this guide.

What the container can already do

Before you install a single extra node, the manifest has already granted the container a set of capabilities that have nothing to do with your flows yet:

These are grants to the container, not permission slips for every flow. Once you install a third-party node it runs with the same process privileges as everything else here — an approved Add-on does not make every npm package on the palette trustworthy. The pinned manifest also locks bcryptjs at 3.0.3 and js-yaml at 5.2.2: the former hashes the wrapper's Basic Authentication, the latter supports the runtime itself. Neither is a node you drag onto a canvas, and neither implies every route shares one login.

Data maps, and what a backup does not include

The manifest's backup_exclude setting drops node_modules. A backup is therefore not a byte-for-byte copy of the running container — after a restore, any custom npm packages have to be reinstalled from a version-pinned list you kept yourself, and the system deserves a real check afterward rather than an assumption that everything came back exactly as it was.

The three-stage boot order, and why one failure stops all of it

Every startup runs a fixed, fail-fast sequence: system_packages, then npm_packages, then init_commands. If any single package install or command in that chain fails, initialization stops right there — it does not skip ahead and try the rest.

flowchart LR
  A["system_packages"] --> B["npm_packages"] --> C["init_commands"] --> S["Normal startup continues"]
  A -.->|"fails"| X["Initialization stops.
Later stages never run"]
  B -.->|"fails"| X
  C -.->|"fails"| X

init_commands runs each line through a shell eval on every single startup. That is arbitrary command execution by design — keep the array empty unless you have a specific, reviewed reason not to, and never put a secret in one of its lines.

Getting in through the sidebar is not the same door as getting in through a port

The Add-on runtime binds the actual Node-RED backend to 127.0.0.1:46836, uses /config/ as its user directory, /config/nodes for extra nodes, flows.json as the flow file, and fixes httpNodeRoot at /endpoint. Inside Node-RED's own settings, adminAuth and https are both null — authentication and TLS are handled one layer up, by the wrapper and NGINX. That delegation is not the same thing as “safe to expose.”

flowchart TD
  A["Open the editor"] --> B{"Through the Home Assistant
sidebar, or a direct host port?"}
  B -->|"sidebar"| C["Ingress. The Supervisor
already confirmed who you are"]
  B -->|"direct port"| D["Direct listener on port 1880"]
  D --> E["ssl: true encrypts the connection.
It does not check who you are"]
  D --> F["The Supervisor auth wrapper
still guards the editor itself"]
  D --> G["/endpoint/ routes skip that wrapper.
http_node is the only thing guarding them"]

ssl: true only turns on HTTPS for the direct listener, reading certfile (default fullchain.pem) and keyfile (default privkey.pem) from /ssl/. A certificate authenticates the server to the client and encrypts the wire; it proves nothing about who is connecting, and it does not stand in for the editor login or for http_node. The documentation also states plainly that HTTP In nodes and dashboards need direct access under Network and a path starting with /endpoint/ — otherwise Home Assistant's own authentication intervenes. A /endpoint/ prefix by itself is not a security control; you still need TLS, real http_node credentials, input validation, and sensible rate and size limits on anything that path exposes.

Every switch in config.yaml, and the ones that are one-way doors

This table reflects the pinned 22.0.1 config.yaml. A default is listed only where the manifest itself defines one; do not copy the sample credentials in any documentation verbatim, since they are explicitly examples, not real values.

The theme list is fixed and long — 35 names in the schema, from default and dark through dracula, tokyo-night, and oled. The initialization program migrates a legacy dark setting to dark-modern automatically; for a fresh configuration, just pick a current name from the list.

The checklist for the first configuration, and every change after it

• Start with theme: default, ssl: true, and the default certificate filenames. Leave system_packages, npm_packages, and init_commands as empty arrays until you have a real, reviewed reason to fill one.
• Leave the direct host port unmapped. If a real requirement forces it open, verify direct TLS, the editor login, http_node, and http_static separately, and restrict which network sources can even reach the port.
• Never enable leave_front_door_open. Use safe_mode only as a temporary recovery step, and review every node with a side effect before turning it back off.
• Keep a controlled, secure copy of credential_secret. It never belongs in a flow, a screenshot, or a repository, and it is not something you change casually once real credentials depend on it.
• Record the purpose and the rollback value before every configuration change. Restart the Add-on afterward as the documentation requires, read the log, then open the Web UI — and pick a maintenance window if real household automations already depend on this being up.
• Plan around backup_exclude: node_modules. Keep a version-pinned list of any custom packages, and actually rehearse a restore rather than assuming it will just work the day you need it.

The failures that actually happen, matched to the layer that caused them

The ones that come up again and again

Where to go from here