{"id":20118511,"url":"https://github.com/flowfuse/device-agent","last_synced_at":"2026-01-27T18:24:57.873Z","repository":{"id":37096596,"uuid":"493613236","full_name":"FlowFuse/device-agent","owner":"FlowFuse","description":"An agent to run FlowFuse managed instances of Node-RED on devices","archived":false,"fork":false,"pushed_at":"2024-09-16T10:19:44.000Z","size":1419,"stargazers_count":15,"open_issues_count":21,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-09-17T02:02:17.415Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FlowFuse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-18T10:22:05.000Z","updated_at":"2024-09-16T10:19:47.000Z","dependencies_parsed_at":"2024-01-16T11:27:30.520Z","dependency_job_id":"2b9ce4c5-92c6-44c9-9527-55dc0060b573","html_url":"https://github.com/FlowFuse/device-agent","commit_stats":{"total_commits":332,"total_committers":14,"mean_commits":"23.714285714285715","dds":0.6445783132530121,"last_synced_commit":"9b693deb0bdf9b9c8c4072bc7b1db380d82c72b8"},"previous_names":["flowfuse/flowforge-device-agent","flowfuse/device-agent","flowforge/flowforge-device-agent"],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlowFuse%2Fdevice-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlowFuse%2Fdevice-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlowFuse%2Fdevice-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlowFuse%2Fdevice-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FlowFuse","download_url":"https://codeload.github.com/FlowFuse/device-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230394228,"owners_count":18218707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T19:11:21.208Z","updated_at":"2026-01-27T18:24:57.866Z","avatar_url":"https://github.com/FlowFuse.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowFuse Device Agent\n\nThis module provides an agent that runs Node-RED instances deployed from the\nFlowFuse platform.\n\n## Prerequisites\n\n - NodeJS v18 or later\n - A FlowFuse platform to connect to\n\n For users that require NodeJS v14 and v16 support the v2.x stream will work.\n\n## Supported Operating Systems\n\nThe Device Agent can be installed on most Linux distributions, Windows, and MacOS.\n\n## Installing the Device Agent\n\nThe Device Agent is published to the public npm repository as [@flowfuse/device-agent](https://www.npmjs.com/package/@flowfuse/device-agent).\n\nIt can be installed as a global npm module. This will ensure the agent command is on the path.\n\nNote: previous versions of the agent were published as `@flowforge/flowforge-device-agent`.\n\n### Linux/MacOS\n\n```bash\nsudo npm install -g @flowfuse/device-agent\n```\n\n### Windows\n\n```bash\nnpm install -g @flowfuse/device-agent\n```\n\n### Docker\n\nWe publish a Docker container for the Device Agent as `flowfuse/device-agent` on DockerHub.\n\nWhen running with the container you will need to mount the `device.yml` obtained when [Registering the device](#register-the-device):\n\n```bash\ndocker run --mount type=bind,src=/path/to/device.yml,target=/opt/flowfuse-device/device.yml -p 1880:1880 flowfuse/device-agent:latest\n```\n\n## Configuration\n\nThe agent configuration is provided by a `device.yml` file within its working\ndirectory.\n\n\n### Configuration directory\n\nBy default the agent uses `/opt/flowfuse-device` or `c:\\opt\\flowfuse-device` as \nits working directory. This can be overridden with the `-d/--dir` option.\n\nFor backwards compatibility with previous versions, the agent will use `/opt/flowforge-device`\nif it is exists, unless overridden on the command-line.\n\nNOTE: The device agent will attempt to create the working directory if it is not found,\nhowever if an error occurs, the device agent will exit and report a startup error.\n\n#### Linux/MacOS\n\n```bash\nsudo mkdir /opt/flowfuse-device\nsudo chown -R $USER /opt/flowfuse-device\n```\n\n#### Windows (run elevated)\n\n```bash\nmkdir c:\\opt\\flowfuse-device\n```\n\n\n### `device.yml` - for a single device\n\nWhen the device is registered on the FlowFuse platform, a group of configuration\ndetails are provided. These can be copied from the platform, downloaded directly\nas a yml file or pulled from the FlowFuse server using the command issued by the\nplatform when you create a device. More details on this can be found\nin the [FlowFuse documentation](https://flowfuse.com/docs/device-agent/introduction/).\n\nThis file should exist in the working directory as `device.yml`.\n\nA different config file can be specified with the `-c/--config` option.\n\nThe file must contain the following options (these are the ones provided by \nFlowFuse)\n\nRequired options   | Description\n-------------------|---------------\n`deviceId`         | The id for the device on the FlowFuse platform\n`token`            | Access Token to connect to the FF platform\n`credentialSecret` | Key to decrypt the flow credentials\n`forgeURL`         | The base url of the FlowFuse platform\n\nTo enable MQTT connectivity, the following options are required. They are provided\nby the platform if MQTT comms are enabled.\n\nMQTT options     | Description\n-----------------|---------------\n`brokerURL`      | The url for the platform broker\n`brokerUsername` | The username to connect with - `device:\u003cteamId\u003e:\u003cdeviceId\u003e`\n`brokerPassword` | The password to connect with\n\nThe following options can be added:\n\nExtra options   | Description\n----------------|---------------\n`interval`      | How often, in seconds, the agent checks in with the platform. Default: 60s\n`intervalJitter`| How much, in seconds, to vary the heartbeat +/- `intervalJitter`. Default: 10s\n`moduleCache`   | If the device can not access npmjs.org then use the node modules cache in `module_cache` directory. Default `false`\n\n\n#### Node-RED options\n\nThe following options are passed through to Node-RED:\n\nNode-RED options | Description\n-----------------|---------------\n`port`           | The port to listen on. Default: 1880\n`https`          | Enable HTTPS. See below for details\n`httpStatic`     | Enable serving of static content from a local path\n`httpNodeAuth`   | If set, any endpoints created in Node-RED flows will require this username and password to access them. Default: `false`\n`localAuth`      | When configured, local login is possible\n\n##### `https` configuration\n\nThe `https` configuration option can be used to enable HTTPS within Node-RED. The values\nare passed through to the [Node-RED `https` setting](https://nodered.org/docs/user-guide/runtime/configuration).\n\nThe `ca`, `key` and `cert` properties can be used to provide custom certificates and keys.\nThe values should be set to the contents of the certificate/key.\n\nAlternatively, the properties `caPath`, `keyPath` and `certPath` can be used instead\nto provide absolute paths to files containing the certificates/keys.\n\n```yml\nhttps:\n   keyPath: /opt/flowfuse-device/certs/key.pem\n   certPath: /opt/flowfuse-device/certs/cert.pem\n   caPath: /opt/flowfuse-device/certs/ca.pem\n```\n\n##### `httpStatic` configuration\n\nThis option can be used to serve content from a local directory.\n\nIf set to a path, the files in that directory will be served relative to `/`.\n\n```yml\nhttpStatic: /opt/flowfuse-device/static-content\n```\n\nIt is also possible to configure it with a list of directories and the corresponding\npath they should be served from.\n\n```yml\nhttpStatic:\n  - path: /opt/flowfuse-device/static-content/images\n    root: /images\n  - path: /opt/flowfuse-device/static-content/js\n    root: /js\n```\n\n##### `httpNodeAuth` configuration\n\nThis option can be used to apply basic auth to HTTP endpoints created in Node-RED.\nThis will also protect node-red-dashboard.\nFull details can be found in [HTTP Node security documentation](https://nodered.org/docs/user-guide/runtime/securing-node-red#http-node-security).\n\nExample:\n```yml\nhttpNodeAuth:\n   user: user\n   pass: $2a$08$zZWtXTja0fB1pzD4sHCMyOCMYz2Z6dNbM6tl8sJogENOMcxWV9DN.\n```\n\n##### `localAuth` configuration\n\nThe recommended way to securely access the Node-RED editor is via FlowFuse platform.\nHowever, if you want to enable local login within Node-RED, you can use the `localAuth` configuration.\n\nExample:\n```yml\nlocalAuth:\n   user: user\n   pass: $2a$08$zZWtXTja0fB1pzD4sHCMyOCMYz2Z6dNbM6tl8sJogENOMcxWV9DN.\n```\n\nNOTE: `localAuth.enabled` can be set to `false` to disable local login without the need to remove the `user` and `pass` properties.\n\nThe editor is located on the path `/device-editor` e.g. `http://localhost:1880/device-editor`\n\n\n### `device.yml` - for provisioning\n\nWhen a device should be auto registered on the FlowFuse platform, a group of provisioning\nconfiguration details are required. These are generated for you in FlowFuse\n**Team Settings** under the **Devices** tab when you create a provisioning token.\nThese can be copied from the platform, or downloaded directly as a yml file.\n\nThis file should be copied into the working directory as `device.yml`.\n\nA different config file can be specified with the `-c/--config` option.\n\nThe file must contain the following options (these are the ones provided by \nFlowFuse)\n\nRequired options    | Description\n--------------------|---------------\n`provisioningName`  | The name of the token\n`provisioningTeam`  | The team this device will be registered to\n`provisioningToken` | Provisioning Token to connect to the FF platform\n`forgeURL`          | The base url of the FlowFuse platform\n`deviceName`        | Device Name (optional)\n\nThe following options can be added:\n\nExtra options   | Description\n----------------|---------------\n`interval`      | How often, in seconds, the agent checks in with the platform. Default: 60s\n`intervalJitter`| How much, in seconds, to vary the heartbeat +/- `intervalJitter`. Default: 10s\n\n## Running\n\nIf the agent was installed as a global npm module, the command \n`flowfuse-device-agent` will be on the path.\n\nIf the default working directory and config file are being used, then the agent\ncan be started with:\n\n```\n$ flowfuse-device-agent\n```\n\nFor information about the available command-line arguments, run with `-h`:\n\n```\nOptions\n\n  -c, --config file     Device configuration file. Default: device.yml\n  -d, --dir dir         Where the agent should store its state. Default: /opt/flowfuse-device\n  -i, --interval secs\n  -p, --port number\n  -m, --moduleCache     Use local npm module cache rather than install\n\nWeb UI Options\n\n  -w, --ui            Start the Web UI Server (optional, does not run by default)\n  --ui-host string    Web UI server host. Default: (0.0.0.0) (listen on all interfaces)\n  --ui-port number    Web UI server port. Default: 1879\n  --ui-user string    Web UI username. Required if --ui is specified\n  --ui-pass string    Web UI password. Required if --ui is specified\n  --ui-runtime mins   Time the Web UI server is permitted to run. Default: 10\n\nSetup command\n\n  -o, --otc string    Setup device using a one time code\n  --otc-no-start      Do not start the agent after setup\n  --otc-no-import     Do not ask to import Node-RED flows during setup\n  -u, --ff-url url    URL of FlowFuse. Required for setup\n\nGlobal Options\n\n  -h, --help       print out helpful usage information\n  --version        print out version information\n  -v, --verbose    turn on debugging output\n```\n\n## Running with no access to npmjs.org\n\nBy default the Device Agent will try and download the correct version of Node-RED and \nany nodes required to run the Snapshot that is assigned to run on the device.\n\nIf the device is being run on an offline network or security policies prevent the \nDevice Agent from connecting to npmjs.org then it can be configured to use a pre-cached \nset of modules.\n\nYou can enable this mode by adding `-m` to the command line adding `moduleCache: true` \nto the `device.yml` file. This will cause the Device Agent to load the modules from the \n`module_cache` directory in the Device Agents Configuration directory as described above.\nBy default this will be `/opt/flowfuse-device/module_cache`.\n\n### Creating a module cache\n\nTo create a suitable module cache, the device must be assigned to an instance.  You will need to\ninstall the modules on a local device with access to npmjs.org, ensuring you use the same\nOS and Architecture as your target device, and then copy the modules on to your device.\n\n1. From the Instance Snapshot page, select the snapshot you want to deploy and select the option to download its `package.json` file.\n2. Place this file in an empty directory on your local device.\n3. Run `npm install` to install the modules. This will create a `node_modules` directory.\n4. On your target device, create a directory called `module_cache` inside the Device Agent Configuration directory.\n5. Copy the `node_modules` directory from your local device to the target device so that it is under the `module_cache` directory.\n\n## Running as a service\n\nAn example service file is provided [here](https://github.com/FlowFuse/device-agent/tree/main/service).\n\n## Running the agent with the Web UI enabled\n\nThe Device Agents Web UI is provided to enable the user to download a device\nconfiguration or a provisioning configuration file. This is an optional feature and\nis not enabled by default.\n\nTo enable the UI, use the `-w/--ui` option. This will start a web server on\nthe specified host and port. The default host is `0.0.0.0` and the default port is `1879`.\n\nWhen enabling the UI, a username and password must be provided with the\n`--ui-user` and `--ui-pass` options.\n\nThe UI will only be available for the duration specified by the `--ui-runtime`. By\ndefault this is 10 minutes. After this time, the web server will be disabled. The \napplication must be restarted to re-enable the UI. You can set this to `0` to \ndisable the timeout. This is not recommended.\n\n## Development\n\n### Scripts\n\nThe following scripts are available:\n\n - `npm start` - Start the agent\n - `npm run dev` - Build the agent and watch for changes\n - `npm run lint` - Run eslint\n - `npm run lint:fix` - Run eslint and fix any issues\n - `npm run test` - Run all unit tests\n - `npm run test:lib` - Run the unit tests for the lib\n - `npm run test:frontend` - Run the unit tests for the frontend\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowfuse%2Fdevice-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflowfuse%2Fdevice-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowfuse%2Fdevice-agent/lists"}