Preface¶

The DSH plugin ecosystem emphasizes “everything is a plugin.” When dsh web needs to run on a remote Linux server, manual setups typically require handling details such as port allocation, registry, systemd services, SSH tunneling, reconnection, and port conflicts. dsh-remote-tunnel encapsulates these steps into dsh, leaving only a single SSH tunnel to the remote host on the local side.

What This Is¶

dsh-remote-tunnel is a Remote Host Tunnel Manager plugin for DSH, maintained by Linjiangxian0203. It targets the “local browser → dsh web on a remote Linux server” link, covering remote port allocation and registry, systemd supervision, resilient SSH tunneling, local URL output, and lifecycle management.

As of 2026-08-30, the version in package.json is 0.1.4, and the license is MIT.

Core Features¶

Below are the verified capabilities.

• Remote Port Allocation: Each user automatically gets an independent remote port, with server-side conflict checks before allocation.
• Registry Records: Each allocation writes to a server-side registry; the default path is /etc/dsh-ports.tsv, with a per-user fallback when permissions are restricted.
• systemd Supervision: Remote services are supervised by systemd; user-level systemd is sufficient, no root required; system units can be used with passwordless sudo.
• Resilient SSH Tunneling: The tunnel automatically reconnects after network interruptions and uses heartbeats to keep registry state fresh.
• Local Port Handling: Automatically shifts to a new port if the local port is occupied, and reports the process causing the conflict.
• Local URL Output: Provides a locally accessible URL once the tunnel is established.
• Lifecycle Management: Provides commands such as status, list, logs, audit, open, and config.
• Host Diagnostics and Preparation: Supports check <host> for readiness diagnostics and provision <host> for remote-side preparation.
• Host Discovery: Automatically discovers Host aliases in ~/.ssh/config.
• Session Location: Sessions and files are stored on the server side; only the tunnel remains local.

Installation and Activation¶

You need Node >= 22.19 locally, and passwordless SSH keys are recommended. The remote server requires Linux, Node >= 22.19, dsh, and systemd.

First, install to the remote profile:

dsh plugin --profile remote add dsh-remote-tunnel

If you also want to see the plugin in the web interface, install it to the web profile:

dsh plugin --profile web add dsh-remote-tunnel

After installing to the web profile, the plugin will appear under Settings → Plugins, and the /remote slash commands will be enabled in chat; then restart dsh web once.

Typical Usage¶

The following is the sequence from host discovery to tunnel startup.

1. View hosts. Host aliases in ~/.ssh/config are automatically discovered.

dsh --profile remote hosts

2. Manually add a host alias. --workspace specifies the workspace directory for the remote dsh web.

dsh --profile remote hosts add lab --host 192.0.2.10 --user alice --workspace /home/alice/project

3. Run initial diagnostics. check performs readiness diagnostics to help identify missing items.

dsh --profile remote check lab

4. Initialize the remote environment. Replace <host> with the target host.

ssh <host> 'sh -s' < scripts/bootstrap-remote.sh

5. Start the tunnel and open the local URL.

dsh --profile remote up lab --open

6. Daily status checks and maintenance.

dsh --profile remote status lab
dsh --profile remote logs lab
dsh --profile remote audit lab
dsh --profile remote down lab

Use Cases and Notes¶

This is suitable for scenarios where dsh web runs on a remote Linux server and the local side only maintains an SSH tunnel. Remote sessions and files reside on the server side, while the local port and tunnel state are managed by the plugin.

Before use, note:

• The plugin and tunnel do not handle credentials; API keys are configured in the remote dsh web’s Settings → Models.
• User-level systemd is sufficient, no root required; using system units typically requires passwordless sudo.
• The registry defaults to /etc/dsh-ports.tsv; whether the server path or the per-user fallback is used depends on permissions.
• If the terminal is force-closed without a Ctrl+C exit, the remote service continues running, and the registry line remains marked as in-use; the next up will clean up stale local state and reuse the same registered port.
• dsh-remote-tunnel runs with the current dsh process permissions. Before installation, review the source code and MIT license to confirm the dependencies and execution methods meet local requirements.
• DSH’s “everything is a plugin” is a community plugin ecosystem concept; the plugin directory is an independent site with no official affiliation to DeepSeek / High-Flyer and should not be considered an official app store.

Links¶

• Plugin Directory: https://www.skillhub.cn/plugins/Linjiangxian0203/dsh-remote-tunnel
• GitHub: https://github.com/Linjiangxian0203/dsh-remote-tunnel