Skip to main content
This guide walks you through installing Sentinel, activating the preload guard, and granting your first capability — from a clean Node-RED setup to a protected runtime.
1

Check prerequisites

Sentinel requires:
  • Node-RED 3.0.0 or later — Sentinel declares "node-red": { "version": ">=3.0.0" } in its manifest and will not load in older runtimes.
  • Node.js — whatever version your Node-RED install already uses is fine.
Confirm your Node-RED version:
node-red --version
2

Install Sentinel into your Node-RED user directory

Sentinel must be installed inside ~/.node-red so that Node-RED auto-discovers it as a plugin:
cd ~/.node-red
npm install @allanoricil/nrg-sentinel
Node-RED scans ~/.node-red/node_modules/ for packages that declare a node-red.plugins field. Sentinel declares one (nrg-sentinel: plugin.js), so the sidebar panel and plugin features load automatically on the next restart — no extra configuration needed for those.
This installs Sentinel’s plugin and preload into your user directory. The Node-RED binary itself stays wherever it was already installed (globally or via a system package).
3

Activate the preload guard

The plugin alone covers the Node-RED API surface. To also gate require() calls for dangerous built-in modules (fs, child_process, vm, worker_threads, and so on), Sentinel’s preload must run before Node-RED’s first require().Start Node-RED with the preload injected:
NODE_OPTIONS="--require @allanoricil/nrg-sentinel/preload" node-red
You must invoke node-red directly — not ./node_modules/.bin/node-red. The node-red package is installed globally, not inside ~/.node-red, so the .bin/ symlink does not exist there. The node-red command in PATH resolves to the correct binary.
4

Grant your first capability

By default Sentinel blocks every privileged operation for every third-party package. The minimum grant any node package needs is registry:register — without it, Sentinel blocks the RED.nodes.registerType() call and Node-RED logs “Waiting for missing types” indefinitely.Add the grant for your custom node in ~/.node-red/settings.js:
settings.js
module.exports = {
    sentinel: {
        allow: {
            // Replace "my-custom-node" with the npm package name exactly as
            // it appears in node_modules/ (e.g. "node-red-contrib-influxdb")
            "my-custom-node": ["registry:register"],
        },
    },
};
Node-RED’s own built-in nodes (inject, debug, function, http request, etc.) live outside the userDir and are never gated by Sentinel. You only need grants for third-party packages installed into ~/.node-red/node_modules/.
5

Start Node-RED and verify Sentinel is active

Start Node-RED with the NODE_OPTIONS flag set:
NODE_OPTIONS="--require @allanoricil/nrg-sentinel/preload" node-red
Look for this line in the startup log — it confirms the preload guard is running:
[@allanoricil/nrg-sentinel] preload guard active
In the Node-RED editor, open the left-hand sidebar. You should see the Sentinel panel listed alongside the standard Info and Debug panels. The panel shows:
  • Active protection status
  • Any blocked operations (with the full call stack and the grant needed to allow them)
  • Package grant management UI
If a node package lacks a required capability, Sentinel logs a blocked-operation warning to the Node-RED console:
[@allanoricil/nrg-sentinel] BLOCKED fs.readFileSync() — my-custom-node lacks fs:read
  Call stack:
    at Object.<anonymous> (/home/user/.node-red/node_modules/my-custom-node/index.js:42:5)
  To allow, add to settings.js:
    sentinel: { allow: { "my-custom-node": ["fs:read"] } }
The warning tells you exactly which capability to add — no guessing required.

​
Next steps

Installation

All installation paths: local, Docker, and build from source

Capability reference

Every capability string, what it gates, and common grant patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us