Installing Device Agent

Choose your install path

Recommended for most users: Use the Device Agent Installer (Quick Start), the fastest way to deploy with minimal configuration. Power users can choose Manual (using npm), Docker, or Kubernetes deployments.

Quick install

Run the one-line installer on your device. It installs Node.js, registers the device on your FlowFuse platform, and configures it to run as a local service.

Linux / macOS

/bin/bash -c "$(curl -fsSL https://flowfuse.github.io/device-agent/get.sh)" && ./flowfuse-device-agent-installer

Windows — run in an elevated PowerShell terminal:

Set-Location $env:USERPROFILE; powershell -c "irm https://flowfuse.github.io/device-agent/get.ps1 | iex"; .\flowfuse-device-agent-installer.exe

See the Quick Start guide for the full walkthrough, or the Installer reference for all options and service management.

  • Recommended: Use the Device Agent Installer
  • Alternative: Manual install (using npm)
    • Install the npm package, set working directory, configure, and run as a service. See Manual install
  • Alternative: Docker / Docker Compose
    • Run the agent in a container; bind-mount the configuration. See Docker install
  • Alternative: Kubernetes

Prerequisites

  • 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
    • mqtt.flowfuse.cloud
  • Access to npm registry when snapshots are installed: https://registry.npmjs.com

Note: The Device Agent downloads the required Node-RED version and any nodes specified by the assigned snapshot. Ensure firewall/proxy permits access to the npm registry or see Running with no access to npmjs.org.

Networking requirements

If you're working behind a firewall, and need to configure it to allow the Device Agent to connect to FlowFuse and the npm registry, see the following:

Allow outbound TCP 443 to:

  • app.flowfuse.com
  • mqtt.flowfuse.cloud
  • registry.flowfuse.cloud
  • registry.flowfuse.com

Ensure access to npm registry to download Node-RED and nodes:

  • https://registry.npmjs.com

For offline environments, see Running with no access to npmjs.org.

Verify the installation

After installing by any method:

  1. Ensure a working directory exists (default is /opt/flowfuse-device or c:\opt\flowfuse-device).
  2. Run the agent and it will help you get it registered, or provide a device configuration you have already created (via Quick Connect, provisioning, or manual device.yml). See Register your Remote Instance.
  3. Start the agent (service or CLI) and open http://<device-ip>:1880 when assigned and running.

What’s next