Device agent 4 related documentation update

docs/device-agent/install/device-agent-installer.md

@@ -128,7 +128,7 @@ To update bundled Node.js runtime, specify the `--update-nodejs` flag with the d
 ./flowfuse-device-agent-installer --update-nodejs --nodejs-version 20.19.1
 ```
 
-Specifying `--update-nodejs` without a version will pick the default version defined in the installer.
+Specifying `--update-nodejs` without a version will pick the default version defined in the installer. From the Device Agent v4 release, the installer defaults to Node.js 22.
 
 ### Device Agent
 To update the Device Agent package, use the `--update-agent` flag, optionally specifying the version:

docs/device-agent/install/docker.md

@@ -57,12 +57,35 @@ services:
       - TZ=UTC
 ```
 
+## Running as a non-root user
+
+From Device Agent v4, the container no longer runs as `root`. It runs as the unprivileged `flowfuse` user (UID `2000` / GID `2000`), following least-privilege security practices.
+
+This affects bind-mounted directories: the directory the agent uses for its state must be writable by UID/GID `2000`, otherwise the agent will fail to start with a permissions error.
+
+Before upgrading an existing container to v4, update the ownership of any mounted directory so the `flowfuse` user can access it:
+
+```bash
+sudo chown -R 2000:2000 /path/to/config/dir
+```
+
+Alternatively, run the container as a user of your choosing with the `--user` flag:
+
+```bash
+docker run \
+  --user 1000:1000 \
+  --mount type=bind,src=/path/to/device.yml,target=/opt/flowfuse-device/device.yml \
+  -p 1880:1880 \
+  flowfuse/device-agent:latest
+```
+
 ## Verify
 
 Once running and assigned, access the Node-RED editor at `http://<device-ip>:1880`.
 
 ## Notes
 
-- Device Agent 3.x requires Node.js 18 in the base image; the `latest` tag uses Node.js 18.
+- Device Agent 4.x defaults to Node.js 22; the `latest` tag now uses Node.js 22. Node.js 20 reached end-of-life in April 2026.
+- Device Agent 3.x uses Node.js 18 in the base image. To stay on a specific line, use a fixed tag instead of `latest`.
 - For 2.x, use a fixed tag like `2.8.0` instead of `latest`.
 - Ensure outbound TCP 443 to `app.flowfuse.com` and `mqtt.flowfuse.cloud` and access to `https://registry.npmjs.com` unless using a module cache. See [Running with no access to npmjs.org](../running.md#running-with-no-access-to-npmjs.org).

docs/device-agent/install/manual.md

@@ -16,7 +16,7 @@ Use this method if you want direct control over the Node.js runtime and filesyst
 
 ## Prerequisites
 
-- Node.js 18 or later installed
+- Node.js 18 or later installed (Node.js 22 recommended; supported versions are 18, 20, 22, and 24). Node.js 20 reached end-of-life in April 2026.
 - Linux, macOS, or Windows
 - Outbound network access to FlowFuse platform and the NPM registry
 
@@ -125,6 +125,6 @@ sudo npm install -g @flowfuse/device-agent@latest
 npm install -g @flowfuse/device-agent@latest
 ```
 
-If you must stay on 2.x, use `@2.x`. Device Agent 3.x requires Node.js 18+.
+If you must stay on 2.x, use `@2.x`. Device Agent 3.x requires Node.js 18+. Device Agent 4.x defaults to Node.js 22 and supports Node.js 18, 20, 22, and 24.
 
 [^1]: Run `powershell -Command "Start-Process 'cmd' -Verb RunAs"` to launch an elevated command prompt (e.g. as an admin user)

docs/device-agent/install/overview.md

@@ -28,7 +28,7 @@ meta:
 
 ## Prerequisites
 
-- Node.js 18 or later (for Manual install and for running locally)
+- Node.js 18 or later (for Manual install and for running locally). Supported versions are 18, 20, 22, and 24. Device Agent v4 (and its installer and official Docker image) defaults to Node.js 22 — this is the recommended runtime. Note that Node.js 20 reached end-of-life in April 2026.
 - Supported OS: Linux, macOS, Windows, or Docker container
 - Networking: allow outbound access on 443 to:
   - app.flowfuse.com

docs/device-agent/running.md

@@ -71,9 +71,10 @@ Setup command
 
 Global Options
 
-  -h, --help       print out helpful usage information
-  --version        print out version information
-  -v, --verbose    turn on debugging output
+  -h, --help          print out helpful usage information
+  --version           print out version information
+  -v, --verbose       turn on debugging output
+  --log-format json   output logs in JSON format
 ```
 
 ### Command Line Examples
@@ -90,6 +91,14 @@ _Start the agent with a different working directory and the Web UI enabled_
 flowfuse-device-agent -d /path/to/working/directory -w --ui-user admin --ui-pass password --ui-port 8081
 ```
 
+## Structured JSON logging
+
+By default the Device Agent prints plain-text logs, which can be hard to parse with log aggregation tools. From Device Agent v4, you can output machine-readable, structured logs in JSON format using the `--log-format json` flag:
+
+```bash
+flowfuse-device-agent --log-format json
+```
+
 ## Configuring Node.js Options
 
 Node.js command-line arguments can be passed to the Node-RED process started by the Device Agent. This is useful for memory-intensive workflows or certificate management.

docs/user/http-access-tokens.md

@@ -40,3 +40,7 @@ To access it from another Node-RED instance, you can use the `HTTP Request` node
 option, selecting 'bearer authentication' and providing the token:
 
 ![](./images/bearer-token-nr-request.png)
+
+### Remote Instances
+
+HTTP Access Tokens can also be used to secure HTTP endpoints served by Node-RED flows running on Remote Instances (devices). This requires [Device Agent v4](../device-agent/introduction.md) or later. On self-hosted FlowFuse, it also requires FlowFuse v2.32 or later.