Preface

In DSH or agent workflows, a common issue is not just whether a single Agent can complete a task, but how parallel local Agents on the same machine—such as dsh, Codex, Claude Code, Hermes, OpenClaw—can send messages to each other. dsh-agent-relay is an MIT-licensed plugin maintained by Noelune that provides a local multi-Agent collaboration relay: secure message passing between local Agents via a loopback-first broker with HMAC authentication.

Plugin Positioning

One-line positioning: dsh-agent-relay is a local multi-Agent message relay plugin.

It provides a local message relay Broker and handles authentication, polling, leasing, retries, and persistence locally; it also offers a dsh Cordis plugin, a CLI client, and a Python client adapter to establish message links between local Agents.

Core Capabilities

  • Provides a local message relay Broker, bound to 127.0.0.1:19121 by default.
  • Uses HMAC-SHA256 signature authentication with built-in timestamp replay protection, authentication failure locking, and per-IP rate limiting.
  • Supports lease/ack reliable delivery, cursor-based incremental polling, lease confirmation, and idempotent deduplication.
  • Messages are retained with a 7-day TTL; SQLite persistence is used by default, falling back to JSONL on older Node versions or explicit configuration.
  • Exponential backoff retries, with examples at 2s/4s/8s.
  • Provides a dsh Cordis plugin that registers agent_relay_send, agent_relay_status, agent_relay_history, agent_relay_peers, and agent_relay_retry model tools.
  • Provides a CLI client and a Python client adapter.
  • Supports a v1 compatibility layer, as well as v2/v3 wire protocols; v3 supports key rotation.
  • The README declares zero third-party runtime dependencies, and package.json indicates Node.js >= 20.

Installation and Enablement

1. Install the Plugin

The official installation command is:

dsh plugin --profile web add dsh-agent-relay

This command mounts the plugin to the web profile.

2. Have DSH Read the Deployment Guide

After installation, you can have DSH read docs/AGENT-DEPLOY.md to automatically generate an HMAC key, start the Broker, configure credentials for dsh, Codex, Claude Code, and the Python client, and run selfcheck.

Typical Usage

Manual CLI Verification

First, clone the repository, initialize, and start the local service:

git clone https://github.com/Noelune/dsh-agent-relay.git && cd dsh-agent-relay
node setup/setup.js init
node setup/setup.js start

Then register an Agent and send/receive messages:

node adapters/cli/relay.mjs register --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs send beta "hello from alpha" --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs recv --agent beta --secret $DSH_RELAY_SECRET

Here, $DSH_RELAY_SECRET is used for HMAC signing. The send command sends a message to beta, and the recv command is used to receive messages on the beta side.

Protocol and Request Headers

v1 client request headers use:

X-Relay-Agent
X-Relay-Timestamp
X-Relay-Signature

v2/v3 client request headers use:

X-Agent-Relay-Agent
X-Agent-Relay-Timestamp
X-Agent-Relay-Signature

v3 can also include:

X-Agent-Relay-Key-Id

v1/v2/v3 protocol formats should not be mixed; generation-specific protocol details are governed by docs/PROTOCOL.md and docs/PROTOCOL-V2.md.

Applicable Scenarios and Considerations

Suitable for DSH users and agent developers who need multiple local Agents on the same host to exchange messages. It is designed for local Agent collaboration links, not for routing local messages through an external message service.

Important considerations before use:

  • This plugin runs within the dsh process and inherits the permissions of the current dsh process. Review the source code and license before installation.
  • The license is MIT, and the README states commercial use is permitted.
  • Default loopback local mode; the README warns against exposing the unencrypted plaintext Broker to public networks.
  • Received message bodies should be treated as unvalidated data input and should not be executed directly as high-privilege commands.
  • Runtime requirement is Node.js >= 20; SQLite default persistence uses Node’s built-in node:sqlite, noting in the README that Node >= 22.5 is required, with no flag needed starting from 22.13+/23.4+; falls back to JSONL on older Node versions or explicit configuration.
  • The Python client adapter is optional and requires Python >= 3.10.
  • The README notes testing and compatibility validation based on dsh 0.1.0-rc.6.
  • The peerDependencies in package.json include @deepseek-ai/cordis ^4.0.1 and @deepseek-ai/dsh-tools ^0.1.0-rc.6.

Conclusion

dsh-agent-relay provides a multi-Agent message link that can run locally: default loopback binding, HMAC authentication, lease/ack delivery, polling, retries, and local persistence.

  • GitHub: https://github.com/Noelune/dsh-agent-relay
  • Directory page (plugin lead, please refer to the directory site’s actual display): https://www.skillhub.cn/plugins/Noelune/dsh-agent-relay