node-red-contrib-fleet-agent

Node-RED agent for NR Fleet Manager — remote management of Node-RED instances via WebSocket.

Allows a central Fleet Manager server to monitor and control your Node-RED instances: restart/stop them, pull git updates, roll back commits, and receive real-time metrics.

Installation

cd ~/.node-red
npm install node-red-contrib-fleet-agent

Or via the Node-RED Manage Palette UI → search for node-red-contrib-fleet-agent.

Nodes

fleet-agent-config (config node)

Stores the connection settings and maintains the persistent WebSocket connection to Fleet Manager.

| Property | Description | |---|---| | Fleet Manager URL | WebSocket URL — supports str, flow, global, env types | | Instance Name | Label shown in Fleet Manager — supports str, flow, global, env, msg types | | Token Source | Direct (encrypted credential) or Environment Variable | | Capabilities | Checkboxes for permitted remote operations |

fleet-agent (network node)

Handles incoming commands from Fleet Manager. Place it in your flow to activate the agent.

• Input → triggers a status report on the output
• Output → msg.payload with { connected, instanceName, capabilities, metrics }

Quick Start

1. Install the package (see above)
2. Add a Fleet Agent Config node (click the pencil icon inside the Fleet Agent node)
3. Set Fleet Manager URL and Agent Token
4. Enable the capabilities you want to allow
5. Deploy — the agent connects automatically

Capabilities

| Key | Label | Description | |---|---|---| | metrics | Send Analytics / Metrics | CPU, memory, uptime reporting | | start | Start Node-RED | Allow remote start | | stop | Stop Node-RED | Allow remote stop | | restart | Restart Node-RED | Allow remote restart | | users | Manage NR Users | View and sync Node-RED admin users | | projects | View Git Projects | List Git projects and sync status | | git_pull | Git Pull | Pull latest commits from git remote | | git_rollback | Git Rollback | Roll back to a previous commit |

Configuration Examples

Token via environment variable (recommended)

Token Source: Environment Variable
Env Variable Name: FLEET_AGENT_TOKEN

export FLEET_AGENT_TOKEN=your-secret-token

Token directly (stored encrypted)

Token Source: Direct (stored securely)
Agent Token: your-secret-token

The token is stored in Node-RED's encrypted credentials file — never in plain text.

Fleet Manager URL from environment

Fleet Manager URL type: env
Value: FLEET_MANAGER_URL

export FLEET_MANAGER_URL=ws://fleet.example.com:3001

Fleet Manager URL from global context

Fleet Manager URL type: global
Value: fleet.url

Set it in Node-RED global context (e.g. via functionGlobalContext in settings.js).

WebSocket Protocol

The agent uses a simple JSON protocol over WebSocket:

Agent → Fleet Manager

| Message type | When sent | Key payload fields | |---|---|---| | register | On connect | instanceName, capabilities, nodeRedVersion, nodeVersion, uptimeSeconds | | heartbeat | Every 30 s | uptimeSeconds, memoryMB, memoryTotalMB, nodeRedVersion | | command_result | After command | commandId, success, error?, result? |

Fleet Manager → Agent

| Message type | Description | Payload fields | |---|---|---| | command | Execute an action | commandId, action, params |

Actions

| action | Required params | Description | |---|---|---| | restart | — | Restart: systemd/pm2 — service restart; direct — watchdog re-launches after 2s | | stop | — | Stop: systemd/pm2 — stop service; direct — process exits (no way to start from Fleet) | | get_metrics | — | Returns system metrics | | git_pull | path, branch | git pull origin <branch> | | git_rollback | path, commitHash | git reset --hard <hash> | | get_projects | userDir? | Scan for git repos in userDir |

Recommendation for production → Run Node-RED under pm2 or systemd so that Start / Stop / Restart from Fleet Manager work reliably. In direct mode, Stop cannot be undone from Fleet (no Start).

Reconnection

The client uses exponential backoff on disconnect: 1s → 2s → 4s → 8s → 16s → 32s → max 60s

Troubleshooting

Node shows "no config" → Add a fleet-agent-config node and link it.

Node shows "no connection — check config" → Fleet Manager URL or Token is empty/invalid. Check the config node settings.

Node stays "connecting…" forever → Verify the Fleet Manager server is running and reachable at the configured URL. → Check that the token is correct. → Look at Node-RED logs for WebSocket errors.

git_pull / git_rollback fails → Ensure Node-RED has read/write access to the project path. → The path must contain a .git directory.

get_projects returns empty array → The userDir path does not contain any directories with a .git folder. → Default: ~/.node-red (or NODE_RED_HOME env var).

Direct mode: Stop vs Restart → Restart: A detached watchdog process starts Node-RED again after ~2s. Requires that the script path can be resolved (process.argv[1], node-red/red.js, or which node-red). If it cannot be resolved, use pm2 or systemd. → Stop: Process exits. There is no way to start Node-RED again from Fleet Manager (the agent is gone). Start it manually, via cron, or use pm2/systemd and the Start command instead.

License

ISC © Andrii Lototskyi