mqtt-bash-exec-channel

A lightweight CLI for Ubuntu 22+ that:

• connects to an MQTT broker
• subscribes to a request topic
• executes bash commands
• publishes command output to a response topic

It runs in the foreground after you start it.

Requirements

• Node.js 18+
• Ubuntu 22.04 or newer
• /bin/bash

Install

npm install

Or install it globally:

npm install -g .

Environment variables

Required:

export BASH_EXEC_CHANNEL_MQTT_BROKER_URL='mqtts://example.ala.cn-hangzhou.emqxsl.cn:8883'
export BASH_EXEC_CHANNEL_MQTT_USERNAME='xxx'
export BASH_EXEC_CHANNEL_MQTT_PASSWORD='xxx'
export BASH_EXEC_CHANNEL_REQUEST_TOPIC='agents/admin/req'
export BASH_EXEC_CHANNEL_RESPONSE_TOPIC='agents/admin/res'

Optional:

export BASH_EXEC_CHANNEL_MQTT_CLIENT_ID='bash-exec-channel-custom'
export BASH_EXEC_CHANNEL_COMMAND_TIMEOUT_MS='300000'
export BASH_EXEC_CHANNEL_MAX_OUTPUT_BYTES='1048576'
export BASH_EXEC_CHANNEL_SHELL='/bin/bash'

If BASH_EXEC_CHANNEL_MQTT_CLIENT_ID is not set, each process start generates a random id like bash-exec-channel-<uuid>.

Run

From the repo:

npm start

Or as a CLI:

mqtt-bash-exec-channel

Testing

Run the fast local test suite:

npm test

Or:

npm run test:fast

This suite only checks local logic and does not require an MQTT broker.

Run the end-to-end smoke suite against a real MQTT broker:

node tests/smoke.test.js \
  --broker-url mqtt://172.16.12.2:1883 \
  --username huozige \
  --password xA123456

Or use environment variables:

export MQTT_TEST_BROKER_URL='mqtt://172.16.12.2:1883'
export MQTT_TEST_USERNAME='huozige'
export MQTT_TEST_PASSWORD='xA123456'
node tests/smoke.test.js

Optional smoke test settings:

• --timeout or MQTT_TEST_TIMEOUT_MS
• --max-output-bytes or MQTT_TEST_MAX_OUTPUT_BYTES

Request payload

Publish this JSON to BASH_EXEC_CHANNEL_REQUEST_TOPIC:

{
  "input": "openclaw agents list",
  "cwd": "~/",
  "threadId": "b-12345"
}

Fields:

• input: command string to execute
• cwd: working directory, supports ~/
• threadId: correlation id returned in the response

Response payload

Published to BASH_EXEC_CHANNEL_RESPONSE_TOPIC:

{
  "threadId": "b-12345",
  "output": "xxxxxxx"
}

Behavior

• commands run through /bin/bash by default on Ubuntu
• received commands are executed strictly one at a time, in arrival order
• stdout and stderr are combined into output
• if the command fails, exit information is appended
• if cwd does not exist, it falls back to the current user's home directory
• output is truncated when it exceeds the configured limit
• invalid JSON or requests without threadId are ignored
• if MQTT is unavailable, the CLI retries every 30 seconds
• if required environment variables are missing, the CLI exits immediately and prints the reason