Introduction

The extension mechanism of DeepSeek Harness (DSH) is primarily based on plugins. Here, “plugins” refer to the capability units for integrating with DSH. The community directory is an independent site with no official affiliation to DeepSeek/Huansuan and should not be understood as an official app store.

For scenarios requiring the invocation of a DSH Agent from an external system, the common practice is to establish a communication channel around a DSH process. UllrAI/dsh-mqtt does the following: allows the DSH process to receive control requests via an MQTT broker and output standardized events and final state results to the client. Below is an introduction to its positioning, capabilities, installation and activation methods, and the boundaries to be aware of.

What is it

dsh-mqtt is an MQTT protocol driver and agent worker gateway for DeepSeek Harness (DSH), maintained by UllrAI, licensed under MIT.

It turns a DSH process into a worker entry point accessible via MQTT: clients send control requests to DSH via MQTT, and DSH outputs standardized session/event, agent status, agent errors, and final state results after execution. The installation version provided in current documentation is 0.1.6, targeting DSH version 0.1.0-rc.8.

Core Capabilities

The capabilities provided by dsh-mqtt focus on MQTT connection, session control, result reliability, and controlled output:

  • MQTT 3.1.1 and MQTT 5 connections, supporting TCP, TLS, WebSocket, and secure WebSocket;
  • Broker authentication, supporting username/password credentials provided directly or via environment variables, custom CA, and optional mutual TLS;
  • Persistent MQTT sessions, reconnection, retained presence, and Last Will;
  • Node-scoped submit, steer, inject, and cancel commands;
  • DSH agent creation and controlled Session continuation;
  • Standardized session/event, agent status, and agent error outputs;
  • QoS 1 request and control deduplication across reconnections and restarts;
  • Durable terminal results and interrupted-request recovery;
  • Use of workspace aliases instead of requiring callers to provide filesystem paths directly;
  • Active-request and payload limits;
  • Default secure event exposure, with support for explicitly enabling full-event opt-in;
  • Versioned topic layout for ACLs.

It is important to emphasize that it is a long-running host plugin, not a model tool like mqtt_publish or mqtt_subscribe. This means it runs alongside the DSH process rather than being called temporarily as a single model tool.

Installation and Activation

First, confirm the environment. The prerequisites listed in the documentation are:

  • Node.js ^22.19.0 or >=24;
  • pnpm available in PATH.

Below are the installation steps.

  1. Use the npm installation command provided in the documentation to add the plugin to the DSH profile:
npx @deepseek-ai/dsh plugin --profile web add dsh-mqtt@0.1.6
  1. Edit the profile configuration file and adjust the mqtt-gateway row:
~/.dsh/profiles/web/cordis.patch.yml

If using a custom $DSH_HOME, also edit the configuration file at the equivalent path.

  1. Check the configuration. The documentation indicates that path fields in the configuration file are parsed by Node.js, where ~ and environment variables are not expanded within these values; therefore, absolute paths should be used. The example configuration includes requireControllerAuth: true; the management API and standalone page listen on loopback by default.

  2. Check the combined profile without starting the full DSH:

npx @deepseek-ai/dsh --profile web --dump-config
  1. Start DSH after setting the provider credential. An example provided in the documentation is:
export DEEPSEEK_API_KEY='...'
npx @deepseek-ai/dsh --profile web
  1. Open DSH settings and select MQTT Worker.

Use Cases and Notes

Situations suitable for using dsh-mqtt typically include:

  • Need to submit requests to a DSH worker via an MQTT broker;
  • Need to observe standardized session/event, agent status, or agent errors;
  • Need to execute node-scoped controls such as submit, steer, inject, cancel;
  • Need broker authentication, custom CA, mutual TLS, persistent sessions, Last Will, and other connection and availability features;
  • Need QoS 1 deduplication, persistent terminal results, and interrupted-request recovery;
  • Need default secure event exposure while retaining the option for explicit full-event opt-in.

Boundaries to be aware of:

  1. dsh-mqtt is a long-running host plugin, not a model tool like mqtt_publish or mqtt_subscribe.
  2. The current version 0.1.6 targets DSH 0.1.0-rc.8. The documentation states that DSH is in developer preview and may introduce breaking changes.
  3. This plugin will run with the permissions of the current dsh process. It is recommended to check the source code and license before installation; the license for this project is MIT.
  4. Configuration file path resolution relies on Node.js. The documentation explicitly states that ~ and environment variables are not expanded in these path values.
  5. The category: 工作流 and stars: 2 provided in the documentation come from the plugin row information; the scraped README and package.json do not display these fields, so they should not be cited as verified facts.

Links