@tbrandenburg/node-red-cli 0.2.8 → 0.2.10

package/README.md

@@ -4,12 +4,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](package.json)
 
-> Install the CLI with `npm install -g @tbrandenburg/node-red-cli`.
-
-## Call Node-RED flows like Unix functions ⚡
-
-`node-red-cli` explores a simple, powerful idea: existing Node-RED flows
-should be usable from a CLI or a Node.js host just like ordinary functions.
+Call existing Node-RED flows from a CLI or a Node.js host, like ordinary
+functions — using the real embedded Node-RED runtime, no flow mutation, no
+temporary nodes.
 
 ```bash
 node-red-cli flows.json calculate --set x=4 --set y=5 < /dev/null
@@ -19,29 +16,50 @@ node-red-cli flows.json calculate --set x=4 --set y=5 < /dev/null
 9
 ```
 
-By default only the resulting payload is printed as plain text. Pass
-`--format=json` to print the full result object as JSON instead:
+This turns Node-RED from a visual automation tool into a reusable runtime
+building block for scripts, services, pipelines, and developer tooling. 🧩
+
+## Install 📦
 
 ```bash
-node-red-cli test/fixtures/flows.json calculate \
-  --set x=4 --set y=5 --format=json < /dev/null
+npm install -g @tbrandenburg/node-red-cli
 ```
 
-```json
-{ "payload": 9, "_msgid": "..." }
-```
+This installs the `node-red-cli` command globally, ready to use against any
+Node-RED flow file (see [Usage](#usage-) below).
 
-This turns Node-RED from a visual automation tool into a reusable runtime
-building block for scripts, services, pipelines, and developer tooling. 🧩
+To build and run from a repo checkout instead (e.g. for contributing):
 
-## Install 📦
+```bash
+make install
+make test
+```
+
+`make install` also wires up a `pre-push` git hook that runs `make ci`
+(format, lint, and tests) automatically before every push. To use
+`node-red-cli` as a regular command from a repo checkout, install it
+globally from the local source:
 
 ```bash
-npm install -g @tbrandenburg/node-red-cli
+make install-global
 ```
 
-This installs the `node-red-cli` command globally, ready to use against
-any Node-RED flow file (see [Quick start](#quick-start-) below).
+## Table of contents
+
+- [The idea](#the-idea-)
+- [Why node-red-cli?](#why-node-red-cli-)
+- [Project layout](#project-layout-)
+- [Usage](#usage-)
+  - [Quick start](#quick-start)
+  - [Passing flow JSON inline](#passing-flow-json-inline)
+  - [Installing additional Node-RED node packages](#installing-additional-node-red-node-packages)
+  - [Running sandboxed in Docker](#running-sandboxed-in-docker-)
+- [Host API](#host-api-)
+- [Technical approach](#technical-approach-)
+- [Preflight and limitations](#preflight-and-limitations-)
+- [Contributing](#contributing-)
+- [Security](#security-)
+- [License](#license-)
 
 ## The idea 💡
 
@@ -77,25 +95,8 @@ no permanently deployed adapter structure. 🚫🔧
   `stderr`.
 - **No flow mutation:** the current implementation adds no temporary nodes and
   never redeploys `flows.json`.
-
-## Current state 🚧
-
-This repository provides an early-stage CLI and host-side adapter for
-Node-RED 5.0.4. The adapter invokes an existing `link in` node and captures
-the response from a `link out` node in return mode as a Promise.
-
-The included example flow (`test/fixtures/flows.json`) computes `x + y`:
-
-```text
-link in: calculate -> Function -> link out: return
-```
-
-The test suite (`test/e2e/flow.e2e.test.js`) verifies:
-
-1. ✅ A successful call returning `{ payload: 9 }`.
-2. ✅ Preflight validation rejecting an unknown target.
-3. ✅ A timeout when a flow doesn't respond in time.
-4. ✅ An unchanged SHA-256 hash of the flow file before and after the call.
+- **Optional sandboxing:** `--docker` re-executes a call inside a disposable,
+  hardened container instead of the host process.
 
 ## Project layout 📁
 
@@ -108,24 +109,9 @@ test/e2e/           Full round trip through the example flow
 test/fixtures/      Example Node-RED flow used as a test asset
 ```
 
-## Quick start 🚀
-
-To build and run from a repo checkout instead (e.g. for contributing):
-
-```bash
-make install
-make test
-```
-
-`make install` also wires up a `pre-push` git hook that runs `make ci`
-(format, lint, and tests) automatically before every push.
-
-To use `node-red-cli` as a regular command from a repo checkout, install it
-globally from the local source:
+## Usage 🚀
 
-```bash
-make install-global
-```
+### Quick start
 
 Try the CLI directly against the example flow:
 
@@ -137,8 +123,18 @@ echo '{"payload":{"x":4,"y":5}}' | node-red-cli test/fixtures/flows.json calcula
 9
 ```
 
-The `_msgid` is generated by Node-RED and differs on every run. To see it
-along with the rest of the result object, pass `--format=json`.
+By default only the resulting payload is printed as plain text. Pass
+`--format=json` to print the full result object as JSON instead (the
+`_msgid` is generated by Node-RED and differs on every run):
+
+```bash
+node-red-cli test/fixtures/flows.json calculate \
+  --set x=4 --set y=5 --format=json < /dev/null
+```
+
+```json
+{ "payload": 9, "_msgid": "..." }
+```
 
 The `target` argument is optional; if the flow has exactly one `link in`
 node, it is used automatically (with a warning on stderr if it also had to be
@@ -163,7 +159,7 @@ node-red-cli test/fixtures/flows.json calculate \
 9
 ```
 
-## Passing flow JSON inline 📥
+### Passing flow JSON inline
 
 Instead of a `<flows.json>` file path, `--flow-json <value>` accepts the flow
 definition directly, so in-memory callers (tests, another Node.js process, a
@@ -200,7 +196,7 @@ node-red-cli --flow-json - calculate --set x=4 --set y=5 \
 9
 ```
 
-## Installing additional Node-RED node packages 📦
+### Installing additional Node-RED node packages
 
 By default the CLI creates a fresh, ephemeral Node-RED `userDir` per
 invocation and deletes it afterwards, so only the node types bundled with
@@ -244,6 +240,59 @@ Node-RED runtime/state files (e.g. `.config.runtime.json`) across runs.
 Delete the directory (or the default `~/.cache/node-red-cli`) to clear the
 cache and start fresh.
 
+### Running sandboxed in Docker 🐳
+
+`--docker [value]` re-executes the _entire_ invocation (flow resolution,
+link call, and any `--node-modules` install) inside a disposable, hardened
+Docker container instead of the host process — useful when `--node-modules`
+installs untrusted community packages, since that's a real code-execution
+surface. Works for both `<flows.json>` (from-file) and `--flow-json` modes,
+with **zero bind mounts and zero leftover host files**: the resolved flow
+and message are streamed over the container's stdin as a single JSON
+envelope, never written to disk.
+
+```bash
+node-red-cli flows.json calculate --set x=4 --set y=5 --docker
+```
+
+`<value>` is one of:
+
+- **omitted (bare flag)**: resolves/builds a locally-cached image tagged
+  `node-red-cli-sandbox:<installed node-red-cli version>`, built from
+  `node:24-slim` + a global `npm install` of this package from the public
+  npm registry. Cached by Docker forever afterward (npm registry versions
+  are immutable, so a version bump is the only thing that invalidates the
+  tag) — later runs of the same version need no network access beyond the
+  container's own sandboxed execution.
+- **`<image[:tag]>`**: use an explicit image. If it already contains the
+  sandbox entrypoint, it's used as-is; otherwise `node-red-cli` is
+  installed into a derived image (`FROM <image>` + a global npm install)
+  on first use, cached by image+version so the check/build only happens
+  once per image.
+- **`@<path>`** or an **http(s) URL**: build from a user-supplied
+  Dockerfile (local file or fetched URL), cached by content hash so an
+  unchanged Dockerfile isn't rebuilt every run.
+
+Sandboxing defaults applied to every `--docker` run:
+
+- `--rm -i` (always disposable)
+- `--network none`, unless `--node-modules` is also given (needs registry
+  access) — narrowest network exposure by default
+- `--read-only` root filesystem + a `/tmp` tmpfs mount
+- `--cap-drop=ALL`
+- `--security-opt=no-new-privileges`
+
+Combined with `--user-dir` + `--node-modules`, persistence uses a
+deterministic **named Docker volume** (derived from the `--user-dir` value)
+mounted inside the container, never a host bind mount — so "no stray host
+files" holds even for persistent installs.
+
+Fails fast with a clear `node-red-cli: docker unavailable: ...` error if
+the Docker CLI/daemon isn't reachable, or `node-red-cli: docker build
+failed: ...` if the image build fails (e.g. the local version isn't yet
+published to npm — use `--docker <image>` or `--docker @path` as an
+escape hatch in that case).
+
 ## Host API 🛠️
 
 The core interface is intentionally small:
@@ -313,38 +362,6 @@ Before a call, `validateTarget(RED, targetId)` checks:
 Validation does not prove that a flow terminates semantically or replies
 exactly once. A runtime timeout remains necessary for that.
 
-## Roadmap 🗺️
-
-The long-term goal is a stable, official host API in Node-RED core:
-
-```js
-const result = await callNodeRedFlow({
-  target: "calculate",
-  msg,
-  timeout: 5000
-});
-```
-
-Or as a runtime interface:
-
-```js
-const result = await RED.runtime.flows.call("calculate", msg, {
-  timeout: 5000
-});
-```
-
-The research focuses on which parts of the existing `node.linkcall()`
-implementation can be generalized, and what a small upstream API such as
-`RED.nodes.callLink()` or `RED.runtime.flows.call()` could look like.
-
-## Status 📊
-
-**Early-stage CLI:** the approach works for the included Node-RED 5.0.4
-example flow. The link-call internals used here are not stabilized as a
-public Node-RED API. Production use therefore requires deliberate version
-pinning, integration tests, and robust error handling for ambiguous or
-non-terminating flows.
-
 ## Contributing 🤝
 
 Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

package/bin/node-red-cli-sandbox-entry.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Container-side entrypoint for `--docker`, set as the sandbox image's
+ * `ENTRYPOINT` (see `src/docker-image.js`). Reads a `{ flow, msg, options }`
+ * envelope as JSON from stdin, runs it against a real Node-RED runtime via
+ * the shared `runFlowInvocation` (the exact same logic the host CLI uses
+ * for its non-Docker path), and writes the formatted result to stdout.
+ */
+
+const { runFlowInvocation } = require("../src/run-envelope");
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
+}
+
+async function main() {
+  let envelope;
+  try {
+    const raw = await readStdin();
+    envelope = JSON.parse(raw);
+  } catch (error) {
+    console.error(`node-red-cli: invalid envelope on stdin: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const { output } = await runFlowInvocation({
+      flow: envelope.flow,
+      msg: envelope.msg,
+      options: envelope.options || {}
+    });
+    process.stdout.write(`${output}\n`);
+  } catch (error) {
+    console.error(`node-red-cli: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/bin/node-red-cli.js

@@ -4,12 +4,11 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { Command } = require("commander");
-const RED = require("node-red");
-const { createHostLinkCaller } = require("../src/link-call");
-const { createMemoryStorageModule } = require("../src/flow-storage");
-const { applySetParams, parseFlowJsonParam, parseFormatParam, formatPlain } = require("../src/cli-params");
+const { applySetParams, parseFlowJsonParam, parseFormatParam } = require("../src/cli-params");
 const { parseNodeModulesParam, resolveUserDir } = require("../src/node-modules");
-const { installMissingNodeModules } = require("../src/node-modules-install");
+const { runFlowInvocation } = require("../src/run-envelope");
+const { resolveImage } = require("../src/docker-image");
+const { runContainer, volumeNameFor, CONTAINER_USER_DIR } = require("../src/docker-run");
 const { version } = require("../package.json");
 
 const HELP_TEXT = [
@@ -58,6 +57,24 @@ const HELP_TEXT = [
   "`npm install`, i.e. arbitrary code execution from the configured npm",
   "registry - only use it with trusted module names.",
   "",
+  "--docker [value] re-executes the entire invocation (flow resolution,",
+  "link call, and any --node-modules install) inside a disposable, hardened",
+  "Docker container instead of the host process. Zero bind mounts, zero",
+  "leftover host files. <value> is one of:",
+  "  - omitted (bare flag): use/build a cached local image",
+  "    node-red-cli-sandbox:<installed version>, from node:24-slim + a",
+  "    global npm install of this package.",
+  "  - '<image[:tag]>': use an explicit image. If it already contains the",
+  "    sandbox entrypoint it is used as-is; otherwise node-red-cli is",
+  "    installed into a derived image on first use (cached by image+version).",
+  "  - '@<path>' or an http(s) URL: build from a Dockerfile (local file or",
+  "    fetched URL), cached by content hash.",
+  "Sandboxing defaults: --network none (unless --node-modules is also set,",
+  "which needs registry access), --read-only rootfs with a /tmp tmpfs,",
+  "--cap-drop=ALL, --security-opt=no-new-privileges. When combined with",
+  "--user-dir, persistence uses a named Docker volume, never a host bind",
+  "mount.",
+  "",
   "Example:",
   '  echo \'{"payload":{"x":4,"y":5}}\' | node-red-cli flows.json calculate',
   "",
@@ -65,31 +82,6 @@ const HELP_TEXT = [
   "  node-red-cli flows.json calculate --set x=4 --set y=5 < /dev/null"
 ].join("\n");
 
-const LEVEL_NAMES = {
-  10: "fatal",
-  20: "error",
-  30: "warn",
-  40: "info",
-  50: "debug",
-  60: "trace",
-  98: "audit",
-  99: "metric"
-};
-
-/**
- * Node-RED's built-in console log handler always writes via console.log,
- * i.e. to stdout. That would corrupt the JSON result on stdout, so replace
- * it with a handler that writes to stderr instead.
- */
-function stderrLogHandler() {
-  return (msg) => {
-    const levelName = LEVEL_NAMES[msg.level] || msg.level;
-    const source = msg.type ? `[${msg.type}:${msg.name || msg.id}] ` : "";
-    const message = msg.msg && msg.msg.message ? msg.msg.message : msg.msg;
-    console.error(`node-red-cli: [${levelName}] ${source}${message}`);
-  };
-}
-
 function readStdin() {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -210,52 +202,66 @@ async function run(args, options) {
     return;
   }
 
-  const userDir =
-    persistentUserDir || fs.mkdtempSync(path.join(require("node:os").tmpdir(), "node-red-cli-"));
+  if (options.docker) {
+    if (!flows) {
+      try {
+        flows = JSON.parse(fs.readFileSync(flowFile, "utf8"));
+      } catch (error) {
+        console.error(`node-red-cli: could not read/parse flow file '${flowFile}': ${error.message}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    const volumeName = persistentUserDir ? volumeNameFor(persistentUserDir) : undefined;
+    const envelope = {
+      flow: flows,
+      msg,
+      options: {
+        target,
+        flow: options.flow,
+        timeoutMs: options.timeout,
+        format: options.format,
+        nodeModules,
+        userDir: volumeName ? CONTAINER_USER_DIR : undefined
+      }
+    };
 
-  if (nodeModules.length > 0) {
+    let image;
+    let result;
     try {
-      await installMissingNodeModules(userDir, nodeModules);
+      image = await resolveImage(options.docker, { version });
+      result = await runContainer(image, envelope, { networkNeeded: nodeModules.length > 0, volumeName });
     } catch (error) {
-      console.error(`node-red-cli: ${error.message}`);
+      console.error(error.message);
       process.exitCode = 1;
-      if (!persistentUserDir) fs.rmSync(userDir, { recursive: true, force: true });
       return;
     }
-  }
 
-  let caller;
-
-  RED.init({
-    ...(flows ? { storageModule: createMemoryStorageModule(flows) } : { flowFile }),
-    userDir,
-    httpAdminRoot: false,
-    httpNodeRoot: false,
-    editorTheme: { projects: { enabled: false } },
-    logging: { console: { level: "warn", metrics: false, audit: false, handler: stderrLogHandler } }
-  });
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exitCode = result.code ?? 1;
+    return;
+  }
 
   try {
-    const flowsStarted = new Promise((resolve) => RED.events.once("flows:started", resolve));
-    await RED.start();
-    await flowsStarted;
-
-    caller = createHostLinkCaller(RED);
-    const result = await caller.call(target, msg, {
-      flow: options.flow,
-      timeout: options.timeout,
-      onWarning: (warning) => console.error(`node-red-cli: warning: ${warning}`)
+    const { output } = await runFlowInvocation({
+      flow: flows,
+      flowFile,
+      msg,
+      options: {
+        target,
+        flow: options.flow,
+        timeoutMs: options.timeout,
+        format: options.format,
+        nodeModules,
+        userDir: persistentUserDir
+      }
     });
-    process.stdout.write(
-      options.format === "plain" ? `${formatPlain(result.payload)}\n` : `${JSON.stringify(result)}\n`
-    );
+    process.stdout.write(`${output}\n`);
   } catch (error) {
     console.error(`node-red-cli: ${error.message}`);
     process.exitCode = 1;
-  } finally {
-    caller?.close();
-    await RED.stop();
-    if (!persistentUserDir) fs.rmSync(userDir, { recursive: true, force: true });
   }
 }
 
@@ -285,6 +291,11 @@ program
     collectNodeModules,
     []
   )
+  .option(
+    "--docker [value]",
+    "run the invocation sandboxed in a disposable Docker container; bare = cached default image, " +
+      "'<image[:tag]>' = explicit image (installed into if missing), '@path'/URL = build from a Dockerfile"
+  )
   .addHelpText("after", HELP_TEXT)
   .version(version, "-v, --version", "print the installed node-red-cli version and exit")
   .action(run);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-cli",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Call existing Node-RED flows from Node.js and the command line",
   "main": "src/link-call.js",
   "bin": {

package/src/docker-image.js

@@ -0,0 +1,211 @@
+"use strict";
+
+/**
+ * Resolves a `--docker [value]` CLI argument into a concrete Docker image
+ * reference, building/caching it via the local Docker daemon as needed.
+ *
+ * Three forms of `value`:
+ * - bare (`true`/`undefined`/`""`): default sandbox image
+ *   `node-red-cli-sandbox:<local package.json version>`, built on demand
+ *   from `node:24-slim` + `npm install -g @tbrandenburg/node-red-cli@<version>`
+ *   the first time that version is needed, then cached by Docker forever
+ *   (npm registry versions are immutable, so the tag is a permanently valid
+ *   cache key - a version bump is the only thing that changes it).
+ * - `<image[:tag]>`: used as-is if it already contains the sandbox
+ *   entrypoint at `SANDBOX_ENTRY_PATH`. Otherwise a derived image is built
+ *   on demand (`FROM <image>` + a global npm install of this package),
+ *   cached by `<image>@<version>` so the check/build only happens once per
+ *   image+version pair.
+ * - `@<path>` or `<http(s)-url>`: build from a user-supplied Dockerfile
+ *   (local file or fetched URL), cached by content hash so an unchanged
+ *   Dockerfile isn't rebuilt every run.
+ *
+ * All failures throw a plain `Error` already carrying the
+ * `node-red-cli: docker ...` prefix convention used throughout the CLI.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { spawnSync, spawn } = require("node:child_process");
+const https = require("node:https");
+const http = require("node:http");
+
+/** Fixed path the default sandbox image installs itself into and the entrypoint runs from. */
+const SANDBOX_ENTRY_PATH =
+  "/usr/local/lib/node_modules/@tbrandenburg/node-red-cli/bin/node-red-cli-sandbox-entry.js";
+
+function isBareValue(value) {
+  return value === true || value === undefined || value === "";
+}
+
+function isDockerfilePath(value) {
+  return typeof value === "string" && value.startsWith("@");
+}
+
+function isUrl(value) {
+  return typeof value === "string" && /^https?:\/\//i.test(value);
+}
+
+/** Fails fast with a clear error if the Docker CLI/daemon isn't reachable. */
+function checkDockerAvailable() {
+  const result = spawnSync("docker", ["info"], { stdio: ["ignore", "ignore", "pipe"] });
+  if (result.error) {
+    throw new Error(`node-red-cli: docker unavailable: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const detail = (result.stderr || Buffer.alloc(0)).toString("utf8").trim();
+    throw new Error(`node-red-cli: docker unavailable: ${detail || "docker info failed"}`);
+  }
+}
+
+function imageExists(tag) {
+  const result = spawnSync("docker", ["image", "inspect", tag], { stdio: ["ignore", "ignore", "ignore"] });
+  return result.status === 0;
+}
+
+/** Checks whether `image` already has the sandbox entrypoint file at `SANDBOX_ENTRY_PATH`. */
+function hasSandboxEntry(image) {
+  const result = spawnSync(
+    "docker",
+    ["run", "--rm", "--entrypoint", "sh", image, "-c", `test -f ${SANDBOX_ENTRY_PATH}`],
+    { stdio: ["ignore", "ignore", "ignore"] }
+  );
+  return result.status === 0;
+}
+
+/** Deterministic derived-image tag for a given base image + node-red-cli version. */
+function derivedTag(image, version) {
+  const hash = crypto.createHash("sha256").update(`${image}@${version}`).digest("hex").slice(0, 16);
+  return `node-red-cli-sandbox-derived:${hash}`;
+}
+
+function derivedDockerfile(image, version) {
+  return [
+    `FROM ${image}`,
+    `RUN npm install -g @tbrandenburg/node-red-cli@${version}`,
+    `ENTRYPOINT ["node", "${SANDBOX_ENTRY_PATH}"]`,
+    ""
+  ].join("\n");
+}
+
+/** Runs `docker build -t <tag> -`, feeding `dockerfileContent` in via stdin (no build context needed). */
+function dockerBuild(tag, dockerfileContent) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("docker", ["build", "-t", tag, "-"], { stdio: ["pipe", "pipe", "pipe"] });
+    let stderr = "";
+    let stdout = "";
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => {
+      reject(new Error(`node-red-cli: docker build failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`node-red-cli: docker build failed: ${(stderr || stdout).trim()}`));
+        return;
+      }
+      resolve();
+    });
+    child.stdin.end(dockerfileContent);
+  });
+}
+
+function defaultDockerfile(version) {
+  return [
+    "FROM node:24-slim",
+    `RUN npm install -g @tbrandenburg/node-red-cli@${version}`,
+    `ENTRYPOINT ["node", "${SANDBOX_ENTRY_PATH}"]`,
+    ""
+  ].join("\n");
+}
+
+function customTag(content) {
+  const hash = crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+  return `node-red-cli-sandbox-custom:${hash}`;
+}
+
+function fetchText(url) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith("https://") ? https : http;
+    client
+      .get(url, (response) => {
+        if (response.statusCode !== 200) {
+          reject(new Error(`HTTP ${response.statusCode}`));
+          response.resume();
+          return;
+        }
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        response.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+async function readDockerfileFrom(value, cwd) {
+  if (isDockerfilePath(value)) {
+    const filePath = path.resolve(cwd, value.slice(1));
+    try {
+      return fs.readFileSync(filePath, "utf8");
+    } catch (error) {
+      throw new Error(
+        `node-red-cli: docker build failed: could not read Dockerfile '${filePath}': ${error.message}`,
+        {
+          cause: error
+        }
+      );
+    }
+  }
+
+  try {
+    return await fetchText(value);
+  } catch (error) {
+    throw new Error(
+      `node-red-cli: docker build failed: could not fetch Dockerfile from '${value}': ${error.message}`,
+      { cause: error }
+    );
+  }
+}
+
+/**
+ * Resolves `dockerValue` (the `--docker [value]` option) into an image
+ * reference, building it if not already cached. `version` is the local
+ * `package.json` version, used for the default (bare) form.
+ */
+async function resolveImage(dockerValue, { version, cwd = process.cwd() } = {}) {
+  checkDockerAvailable();
+
+  if (isBareValue(dockerValue)) {
+    const tag = `node-red-cli-sandbox:${version}`;
+    if (!imageExists(tag)) {
+      await dockerBuild(tag, defaultDockerfile(version));
+    }
+    return tag;
+  }
+
+  if (isDockerfilePath(dockerValue) || isUrl(dockerValue)) {
+    const content = await readDockerfileFrom(dockerValue, cwd);
+    const tag = customTag(content);
+    if (!imageExists(tag)) {
+      await dockerBuild(tag, content);
+    }
+    return tag;
+  }
+
+  // Explicit image[:tag] reference: use as-is if it already has the sandbox
+  // entrypoint, otherwise install node-red-cli into a derived image on
+  // first use (cached by image+version, so this only happens once).
+  if (hasSandboxEntry(dockerValue)) {
+    return dockerValue;
+  }
+
+  const tag = derivedTag(dockerValue, version);
+  if (!imageExists(tag)) {
+    await dockerBuild(tag, derivedDockerfile(dockerValue, version));
+  }
+  return tag;
+}
+
+module.exports = { resolveImage, SANDBOX_ENTRY_PATH };

package/src/docker-run.js

@@ -0,0 +1,84 @@
+"use strict";
+
+/**
+ * Builds and executes the hardened `docker run` invocation for `--docker`:
+ * streams the envelope (`{ flow, msg, options }`) over stdin to a disposable
+ * container running the resolved sandbox image, relays stdout/stderr/exit
+ * code back to the host.
+ *
+ * Sandboxing defaults (always applied):
+ * - `--rm -i` (always disposable, interactive stdin)
+ * - `--network none`, unless `networkNeeded` (i.e. `--node-modules` is set)
+ * - `--read-only` root filesystem + a `/tmp` tmpfs mount
+ * - `--cap-drop=ALL`
+ * - `--security-opt=no-new-privileges`
+ *
+ * When `volumeName` is given (derived from `--user-dir`, see
+ * `volumeNameFor`), it is mounted as a named Docker volume at
+ * `CONTAINER_USER_DIR` instead of a host bind mount, so `--user-dir` +
+ * `--node-modules` persistence never touches the visible host filesystem.
+ */
+
+const crypto = require("node:crypto");
+const { spawn } = require("node:child_process");
+
+/** Fixed in-container mount path for the `--user-dir` named volume. */
+const CONTAINER_USER_DIR = "/data/userDir";
+
+/** Deterministic named-volume name for a given `--user-dir` path, so repeat runs reuse the same volume. */
+function volumeNameFor(userDirPath) {
+  const hash = crypto.createHash("sha256").update(userDirPath).digest("hex").slice(0, 16);
+  return `node-red-cli-userdir-${hash}`;
+}
+
+function buildRunArgs(image, { networkNeeded, volumeName }) {
+  const args = ["run", "--rm", "-i"];
+  if (!networkNeeded) args.push("--network", "none");
+  args.push("--read-only", "--tmpfs", "/tmp", "--cap-drop=ALL", "--security-opt=no-new-privileges");
+  if (networkNeeded) {
+    // --node-modules runs a real `npm install`, which needs a writable cache
+    // dir; point it at the /tmp tmpfs since the root filesystem is read-only.
+    args.push("-e", "npm_config_cache=/tmp/.npm-cache");
+  }
+  if (volumeName) args.push("-v", `${volumeName}:${CONTAINER_USER_DIR}`);
+  args.push(image);
+  return args;
+}
+
+/**
+ * Runs `envelope` through the resolved sandbox `image` in a disposable,
+ * hardened container. Resolves with `{ code, stdout, stderr }` on any
+ * container exit (including non-zero, which is the flow's own error exit
+ * code, not a docker-orchestration failure); rejects only when `docker run`
+ * itself could not be spawned or exited before the container's own process
+ * ran (docker CLI missing, daemon unreachable, invalid image, etc.).
+ */
+function runContainer(image, envelope, { networkNeeded = false, volumeName } = {}) {
+  const args = buildRunArgs(image, { networkNeeded, volumeName });
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("docker", args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let spawnFailed = false;
+
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => {
+      spawnFailed = true;
+      reject(new Error(`node-red-cli: docker run failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (spawnFailed) return;
+      resolve({ code, stdout, stderr });
+    });
+
+    child.stdin.on("error", () => {
+      // A broken pipe here (e.g. the container failed to start) is reported
+      // via the 'close'/'error' handlers above; swallow the EPIPE itself.
+    });
+    child.stdin.end(JSON.stringify(envelope));
+  });
+}
+
+module.exports = { runContainer, buildRunArgs, volumeNameFor, CONTAINER_USER_DIR };

package/src/run-envelope.js

@@ -0,0 +1,103 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const RED = require("node-red");
+const { createHostLinkCaller } = require("./link-call");
+const { createMemoryStorageModule } = require("./flow-storage");
+const { formatPlain } = require("./cli-params");
+const { installMissingNodeModules } = require("./node-modules-install");
+
+const LEVEL_NAMES = {
+  10: "fatal",
+  20: "error",
+  30: "warn",
+  40: "info",
+  50: "debug",
+  60: "trace",
+  98: "audit",
+  99: "metric"
+};
+
+/**
+ * Node-RED's built-in console log handler always writes via console.log,
+ * i.e. to stdout. That would corrupt the JSON result on stdout, so replace
+ * it with a handler that writes to stderr instead.
+ */
+function stderrLogHandler() {
+  return (msg) => {
+    const levelName = LEVEL_NAMES[msg.level] || msg.level;
+    const source = msg.type ? `[${msg.type}:${msg.name || msg.id}] ` : "";
+    const message = msg.msg && msg.msg.message ? msg.msg.message : msg.msg;
+    console.error(`node-red-cli: [${levelName}] ${source}${message}`);
+  };
+}
+
+/**
+ * Runs a single link-call invocation against a real, freshly booted
+ * Node-RED runtime: installs any missing `--node-modules`, boots RED with
+ * either an in-memory flow array (`flow`) or a flow file path (`flowFile`),
+ * calls the target link-in node, tears everything down again, and returns
+ * the formatted stdout output.
+ *
+ * This is the single shared implementation used by both the host CLI
+ * (`bin/node-red-cli.js`, non-Docker path) and the containerized sandbox
+ * entrypoint (`bin/node-red-cli-sandbox-entry.js`, `--docker` path), so both
+ * execute the exact same runtime logic.
+ *
+ * `options.userDir`, when set, is treated as a persistent directory and is
+ * never removed afterward (host: an explicit `--user-dir`; container: the
+ * fixed mount path of a named Docker volume). When omitted, an ephemeral
+ * tmpdir is created and removed again after the call.
+ */
+async function runFlowInvocation({ flow, flowFile, msg, options }) {
+  const {
+    target,
+    flow: flowSelector,
+    timeoutMs = 5000,
+    format = "plain",
+    nodeModules = [],
+    userDir: fixedUserDir
+  } = options;
+
+  const persistentUserDir = Boolean(fixedUserDir);
+  const userDir = fixedUserDir || fs.mkdtempSync(path.join(os.tmpdir(), "node-red-cli-"));
+
+  try {
+    if (nodeModules.length > 0) {
+      await installMissingNodeModules(userDir, nodeModules);
+    }
+
+    let caller;
+    RED.init({
+      ...(flow ? { storageModule: createMemoryStorageModule(flow) } : { flowFile }),
+      userDir,
+      httpAdminRoot: false,
+      httpNodeRoot: false,
+      editorTheme: { projects: { enabled: false } },
+      logging: { console: { level: "warn", metrics: false, audit: false, handler: stderrLogHandler } }
+    });
+
+    try {
+      const flowsStarted = new Promise((resolve) => RED.events.once("flows:started", resolve));
+      await RED.start();
+      await flowsStarted;
+
+      caller = createHostLinkCaller(RED);
+      const result = await caller.call(target, msg, {
+        flow: flowSelector,
+        timeout: timeoutMs,
+        onWarning: (warning) => console.error(`node-red-cli: warning: ${warning}`)
+      });
+      return { output: format === "plain" ? formatPlain(result.payload) : JSON.stringify(result) };
+    } finally {
+      caller?.close();
+      await RED.stop();
+    }
+  } finally {
+    if (!persistentUserDir) fs.rmSync(userDir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { runFlowInvocation, stderrLogHandler };