Preface

When running a DeepSeek Harness (DSH) session locally, you typically cannot expose it to external networks or receive remotely triggered requests. dsh-maestro-remote is designed to solve this problem by establishing a path to the internet through a Cloudflare Tunnel and providing a PIN-authenticated remote proxy. It also supports receiving Webhooks from services such as GitLab through the tunnel ingress.

Plugin Overview

This is a plugin that adds remote access capabilities to DeepSeek Harness. It uses a Cloudflare Tunnel to expose local services to the public internet and protects the proxy entry point with a PIN authentication mechanism. This plugin is part of the Maestro Harness suite (dsh-maestro-*).

Core Features

The plugin includes the following capabilities:

  1. Tunnel Lifecycle Management
    - Supports starting, stopping, and querying tunnel status.
    - Supports quick tunnels or named tunnels.
    - Automatically resumes previously running named tunnels when the system starts.

  2. Remote Proxy and Authentication
    - Provides a remote proxy service, with request handling protected by PIN authentication (using a constant-time comparison algorithm).
    - Supports configuration reloading.

  3. Traffic Routing
    - By default, routes non-Webhook traffic to the remote proxy.
    - Supports routing GitLab Webhook requests through the tunnel ingress (/hooks/*).

  4. Cloudflared Management
    - Automatically resolves the cloudflared binary in PATH; if it does not exist, it automatically downloads it to a cache directory.

Configuration and Dependencies

The plugin requires a Node.js environment, and the version must satisfy ^22.19.0 || >=24.0.0.

Configuration data is persistently stored in the shared namespace settings file (~/.dsh/maestro/settings.json), while machine runtime state (such as lastTunnelRunning) is stored in the plugin’s own Sidecar directory (~/.dsh/dsh-maestro-remote/runtime.json). This separation is designed to prevent accidental changes to tunnel runtime state while editing configuration.

Installation and Enablement

Install the plugin with the following command:

dsh plugin --profile web add @ddtcorex/dsh-maestro-remote

Before installing, make sure the source code meets your requirements and that the MIT license permits your intended use case.

Usage Notes

Configuration is managed through the shared namespace settings, so no separate configuration file is required.

Note that changes to tunnel configuration (such as changing the tunnel name or ingress rules) must be verified through a real-time start/stop cycle to ensure they take effect. See AGENTS.md for details.

Applicable Scenarios and Considerations

This plugin is suitable for developers who need to access DSH sessions in remote network environments or trigger local agent tasks through a public tunnel, such as receiving GitLab Webhooks.

References