Skip to main content

deepseek-harness-desktop/packages/dsh-ssh

156Stars5Forks6Issues0Watchers

Add full SSH operation capabilities to dsh Web GUI: host management, persistent connection pool, command execution, web terminal, SFTP file transfer, local port forwarding, cluster concurrent execution, and Agent tools for 6 shared host configurations.

Categories▣ UI Enhancements⌨ Developer Tools⇄ Integrations
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
ningbainbningbainb
·ningbainb/deepseek-harness-desktop·ningbainb.github.io/deepseek-harness-desktop
Language
TypeScript
License
BSD-3-Clause
Branch
main
ai-agentai-coding-assistantcodexdeepseekdeepseek-harnessdesktop-appdshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add @linxin666/dsh-ssh

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin ningbainb/deepseek-harness-desktop/packages/dsh-ssh for me: review the repository at https://github.com/ningbainb/deepseek-harness-desktop first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Sentence Description

Adds a complete set of SSH operations capabilities to the dsh Web GUI: centralized management of multiple remote hosts on the web side (CRUD, search, connection testing, one-click import from ~/.ssh/config), persistent ssh2 connection pool reuse in the host process to execute commands, run Web terminals, transfer SFTP files, open local port forwarding tunnels, and run the same command concurrently on multiple hosts; also provides 6 tools for the Agent to share the same host configuration.

Core Features

  • Host CRUD, search, connection testing; supports key/password authentication, passphrase-protected keys, ProxyJump multi-level jump hosts
  • One-click import from ~/.ssh/config: parses Host / HostName / User / Port / IdentityFile / ProxyJump fields, skips existing aliases automatically
  • Persistent ssh2 connection pool: each host reuses a single long-lived connection (no reconnect each time), auto-disconnects after 30 minutes idle, auto-reconnect on disconnect (max 3 times)
  • Command execution: single-host exec with timeout (default 60s, overridable), stdout/stderr separation, 2MB truncation protection per output; cluster concurrent execution (default concurrency 8, filterable by alias/environment/tags)
  • Web terminal (xterm.js + WebSocket PTY, backpressure auto-pause/resume), SFTP file transfer (upload via NDJSON progress stream, download returns binary stream), local port forwarding tunnel (listens only on 127.0.0.1, access remote databases/internal services), Linux host real-time monitoring (CPU/memory/disk/load/process/systemd anomalies, 3s refresh)
  • Agent tools ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster, GUI and Agent share the same host configuration

Technical Implementation

  • Language: TypeScript
  • Key Dependencies: ssh2 (Node-side SSH client), @xterm/xterm + @xterm/addon-fit (browser terminal), ws (WebSocket upgrade to carry PTY), @deepseek-ai/dsh-tools (Agent tool definitions)
  • Architecture Pattern: Dual half-zone cordis plugin — host half-zone (src/index.ts) starts SshEngine, registers /api/dsh-ssh/* routes and WebSocket terminals, registers 6 Agent tools, injects system prompts; client half-zone (src/client/index.ts) injects sidebar entry via DOM + mounts React panel (six tabs). Through cordis.patch.yml inject bundle line with id: ssh in web profile, only modifies DSH service discovery, does not change DSH source code.
  • Entry Files: packages/dsh-ssh/src/index.ts (host half-zone), packages/dsh-ssh/src/client/index.ts (browser half-zone)

Use Cases

When users need to manage multiple remote servers simultaneously in the dsh Web GUI, this plugin centralizes SSH host configuration, remote commands, web terminals, file transfers, and port forwarding all in the browser, enabling the AI Agent to perform remote operations on the same host configuration. Typical scenarios: ops teams one-click import existing ~/.ssh/config, then perform service health checks, batch script deployment, file distribution, and internal database port forwarding across multiple machines directly in the browser.

Prerequisites and Compatibility

DependencyMinimum VersionDescription
Node.js^22.19.0 || >=24.0.0From package.json engines field
DSH (Official SDK)Locked via devDependencies to ^0.1.0-rc.7package.json does not declare dsh.engines, requires DSH 0.1.0-rc.7+ to resolve all runtime injections
React^18.2.0 (peerDependencies)Browser half-zone panel runtime environment
PlatformCross-platformHost half-zone runs Node.js; client half-zone runs browser; ssh2 is pure JS library, no native module restrictions
Native ModulesNoneNo native Node modules at runtime; ssh2 is pure JS SSH client, no native bindings

Installation

dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-ssh

Configuration Options

ConfigTypeDescriptionDefault
enabledbooleanMaster switch: when disabled, all routes, Agent tools, and system prompt declarations stop mountingtrue
announceToAgentbooleanWhether to declare this plugin's capabilities and limitations to the Agent in system prompts; when disabled, Agent cannot see SSH toolstrue
Host Aliasstringopenpanel/sidebar/Agent all call by this alias, rules: letter-starting letter/number/dot/hyphen/underscoreUser configures in GUI
~/.ssh/config ImportOne-time operationOne-click import on host management page; existing aliases are skipped automatically—

The engine also has 8 runtime constants (idle timeout 30 minutes, connection timeout 15s, keepalive 15s, max output 2MB, exec default timeout 60s, cluster default concurrency 8, SFTP concurrency 8, keepalive failure 3 times to disconnect), these are hardcoded internally in host, not exposed to user settings.

FAQ

Q: Can others in the LAN access my SSH console?

A: No. All /api/dsh-ssh/* routes perform loopback validation (socket must be 127/8 or ::1, plus same-origin Host/Origin header validation), direct access from LAN neighbors is rejected; local port forwarding tunnels also only listen on 127.0.0.1, not exposed to external networks.

Q: How are passwords saved? Can others see them?

A: Stored in plain text at ~/.dsh/dsh-ssh.json (file permission 0600, directory 0700, atomic write), same trust model as ssh-skill writing passwords in ssh-config comments. No additional encryption by design, as encryption would introduce new key management burden; users should ensure their local account security.

Q: Will the Agent execute commands on hosts I haven't configured?

A: No. The Agent can only operate on host aliases configured in GUI or imported from ~/.ssh/config; when an alias is not configured, tool calls directly error without fabricating hosts — this is explicitly declared in system prompts.

Q: What if remote command times out or output is very large?

A: Exec default timeout is 60 seconds (can be overridden), after timeout it sends KILL to remote stream and forces cleanup; if stdout/stderr accumulated exceeds 2MB in a single run, it automatically truncates and marks [output truncated], preventing a single command from spewing GBs and blowing up the process.

Q: How to use jump hosts and cluster execution?

A: Fill proxyJump array in host config (each hop must be a host alias already configured in this plugin), the engine will chain-connect in order via forwardOut. Cluster execution filters by alias/environment/tags in the "Cluster" tab or via ssh_cluster tool, tags use ALL semantics for full match, default concurrency 8 is adjustable.

Q: Will uninstalling the plugin clear my configured hosts?

A: No automatic deletion. ~/.dsh/dsh-ssh.json is a user data file, plugin install/uninstall only affects engine, routes, Agent tool mounting and deregistration; to clean up completely, manually delete or rename the file.

Learning Curve

Advanced — configuring hosts, keys, and jump hosts requires SSH basics; host management, terminal, and file transfer in GUI are straightforward, but the collaboration model between Agent tools and system prompts requires some time to understand.

Known Issues and Limitations

  • Remote target path for file uploads must be absolute (relative paths error at upload entry).
  • Download does not support entire directories (file-by-file download only); upload supports recursive directories (walks local directory, transfers files one by one).
  • Exec auto-reconnect on disconnect (max 3 times) may replay non-idempotent commands, please confirm idempotency before use for long-running tasks (deployments, database migrations).
  • Each hop in ProxyJump jump host must be a host alias already configured in this plugin, cannot directly write IP/domain.
  • Resume (断点续传) not yet implemented.
  • Paths for Agent tools ssh_upload / ssh_download are host machine local paths (not via bash sandbox), same semantics as ssh-skill, note this permission surface.
  • Remote output from exec/cluster is returned as-is (not sanitized), commands like env may bring back keys from remote environment into conversation history.

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-ssh)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory