node-red-contrib-fleet-agent 0.1.1
Node-RED agent for NR Fleet Manager (https://github.com/lotockii/nr-fleet-manager) — remote management via WebSocket
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.payloadwith{ connected, instanceName, capabilities, metrics }
Quick Start
- Install the package (see above)
- Add a
Fleet Agent Confignode (click the pencil icon inside the Fleet Agent node) - Set Fleet Manager URL and Agent Token
- Enable the capabilities you want to allow
- 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
