node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org ¬Ľ



npm version License

Advanced process control via MQTT ūüď°



Needs Node.js and npm.

npm install -g mqttpc

Command line options

Usage: index.js [options]
  -v, --verbosity  possible values: "error", "warn", "info", "debug"
                                                               [default: "info"]
  -n, --name       instance name. used as mqtt client id and as prefix for
                   connected topic                               [default: "pc"]
  -u, --url        mqtt broker url. See
                                                   [default: "mqtt://"]
  -f, --config     config file                         [default: "./procs.json"]
  -h, --help       Show help                                          
  --version        Show version number

Config file

The config file contains a JSON definition of all processes you want to control via MQTT:

  "<process_name>": {
    "path": "/usr/bin/example",
    "args": ["-x", "-y"],

Availabe attributes

The only mandatory attribute for each process is "path", all others are optional.

  • path - (string) path to the process
  • args - (array[string]) arguments
  • cwd - (string) the working directory (default: the cwd of mqttpc)
  • env - (object) key-value paired environment (default: the env of mqttpc)
  • uid - (number) user id
  • gid - (number) group id
  • shell - (boolean|string) run command in a shell (default: false). See
  • disableStdin - (boolean) Disable the possibility to send data through MQTT to the process stdin (default: false).
  • disableStdout - (boolean) Disable MQTT publish of the process stdout (default: false).
  • disableStderr - (boolean) Disable MQTT publish of the process stderr (default: false).

Usage example

Let's say we got a backup script located in /usr/local/bin/ that we want to control via MQTT.

Create a config entry like this:

    "my-backup": {
        "path": "/usr/local/bin/"

...and (Re)start mqttpc. Now you can start your Backup Script by publish on pc/set/my-backup/spawn (Payload is irrelevant). If you want to stop your script via MQTT you could publish SIGKILL on the topic pc/set/my-backup/signal.

Topics mqttpc publishes


After process start the pid is published retained. When process ends an empty payload will be published (removing the retained message).


After process exit the exit code (or the killing signal) will be published retained.


Errors on process spawn will be published retained on this topic. On next successful process start an empty payload will be published (removing the retained message).


The processes stdout will be published on this topic (not retained).


The processes stderr will be published on this topic (not retained).

Topics mqttpc subscribes


Start the process


Pipe payload into stdin of the process


Send a signal to the process (Payload should be a string containing the signal name, e.g. "SIGHUP")


MIT (c) Sebastian Raff