Skip to main content

dsh-ui-web/packages/dsh-ssh

34Stars2Forks0Issues0Watchers

Adds complete SSH operations to DSH Web GUI: host management, web terminal, SFTP transfer, local port forwarding tunnels, cluster concurrent execution, and 6 Agent tools. Configuration is centrally stored locally.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the CAPTAIN1275/dsh-ui-web monorepo — stars and activity count the whole repository.

Language
TypeScript
License
Apache-2.0
Branch
main
dsh-plugindsh-plugin-marketdsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add @captain1275/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 CAPTAIN1275/dsh-ui-web/packages/dsh-ssh for me: review the repository at https://github.com/CAPTAIN1275/dsh-ui-web 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-Line Positioning

Adds complete remote SSH operations capability to the DSH Web GUI: centrally manage multiple remote hosts from the web (CRUD, search, connection testing, one-click import from ~/.ssh/config), reuse persistent ssh2 connection pools within the host process to execute commands, run Web terminals, transfer SFTP files, open local port forwarding tunnels, and concurrently run the same command across multiple hosts; also provides 6 tools for the Agent, sharing the same host configuration.

Core Features

  • Host CRUD, search, connection testing; supports key / password authentication, passphrase-protected keys, multi-level ProxyJump jump hosts (each hop must be an alias already configured in this plugin)
  • One-click import from ~/.ssh/config: parses Host / HostName / User / Port / IdentityFile / ProxyJump fields, skips existing aliases (wildcard mode / skips if HostName missing)
  • Persistent ssh2 connection pool: each host reuses one long 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), stdout / stderr separation, 2MB truncation protection per output
  • Web terminal (xterm.js + WebSocket PTY, backpressure auto-pause / resume), SFTP file transfer (browser file selection → NDJSON progress stream), local port forwarding tunnel (listens only on 127.0.0.1, access remote DB / intranet services), cluster concurrent execution (default concurrency 8, filterable by alias / env / tag)
  • 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 (host half src/index.ts) + TypeScript + React 18 + CSS Modules (browser half src/client/)
  • Key Dependencies: ssh2 ^1.17.0 (persistent ssh2 connection pool + SFTP), @xterm/xterm ^6.0.0 + @xterm/addon-fit ^0.11.0 (browser terminal), ws ^8.18.0 (WebSocket PTY)
  • Architecture Pattern: Dual-half cordis bundle. src/index.ts is the host half (SshEngine connection pool + /api/dsh-ssh/* routes + 6 Agent tools + system prompt declaration), src/client/index.ts is the browser half (sidebar entry + host management / terminal / transfer / tunnel / cluster panels + locale registration). Bundle declaration in packages/dsh-ssh/cordis.patch.yml:10-12 (inserts id ssh), browser side injects 3 official @deepseek-ai/dsh-client-* via dsh.client.inject (client-runtime / client-connection / client-ui-settings) + platform: web. Connection pool default parameters: 30 min idle, 15s handshake timeout, 15s keepalive interval, 2MB output cap, 60s exec default timeout, cluster concurrency 8, SFTP concurrency 8 (src/engine.ts:33-41)
  • Entry Files: packages/dsh-ssh/src/index.ts (host apply), packages/dsh-ssh/src/client/index.ts (browser apply); bundle declaration packages/dsh-ssh/cordis.patch.yml:1-12, browser dependencies packages/dsh-ssh/package.json:31-39

Use Cases

  • Developers who need to manage multiple SSH servers daily (dev/test/prod mixed): want to centrally browse hosts, execute commands, transfer files, open tunnels to access remote DB / intranet services in DSH Web GUI, saving tool switching;
  • Developers who want Agents to directly execute remote operations tasks: pre-configure hosts in GUI (manual entry or import from ~/.ssh/config), then Agent can call the same host configuration via ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster;
  • Users with existing ~/.ssh/config: use "Import ssh_config" to one-click sync existing SSH aliases to the plugin, no duplicate host/port/user/identityFile entry needed.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSH Host0.1.0-rc.6+peerDependencies locked to @deepseek-ai/dsh-* ^0.1.0-rc.6
Node.js^22.19.0 or >=24.0.0package.json engines.node
PlatformmacOS / Windows / Linuxhost half runs Node.js, client half runs browser; ssh2 is pure JS library, no OS restriction
Native ModulesNone (runtime)ssh2 needs no native bindings; upload/download uses ssh2's built-in SFTP
React^18.2.0peerDependency, injected by host runtime
SSH ServerAny standard OpenSSHhost half acts as ssh2 client, no server version dependency

Installation

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-ssh

Configuration Options

This plugin provides 2 toggles in the "SSH" section of the dsh settings panel:

ConfigTypeDescriptionDefault
enabledtogglePlugin master switch; when off, does not register /api/dsh-ssh/* routes, does not register Agent tools, does not announce to Agenttrue
announceToAgenttoggleWhether to announce this plugin in system prompts (when off, Agent cannot see SSH tools)true

There are also some hardcoded constants not exposed to GUI in the engine (src/engine.ts:33-41): 30 min idle timeout, 15s handshake timeout, 15s keepalive interval, 3 keepalive retry limit, 2MB output cap, 60s exec default timeout, cluster default concurrency 8, SFTP concurrency 8; upload single request body cap 4 GiB, WebSocket terminal backpressure 1MB/512KB (src/routes.ts:23-39). Adjusting requires code changes and rebuild.

FAQ

Q: After installation, the SSH entry doesn't appear in the sidebar. What should I do?

A: Restart dsh web. Bundle activation is done once at host startup; refreshing the browser is not enough. After restart, the "SSH" entry appears in the sidebar, and the Agent prompt will automatically include the plugin description (controlled by the announceToAgent toggle).

Q: How are passwords stored? Is it secure?

A: Stored in plaintext at ~/.dsh/dsh-ssh.json, file permission 0600, directory permission 0700, atomic write (tmp + rename). This is the same trust model as ssh-skill storing passwords in ~/.ssh/config comments - since ~/.ssh/config often stores passwords as comments too, this plugin does not add extra encryption. File path and permissions in src/store.ts:18-20, src/store.ts:328-336.

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

A: No. All /api/dsh-ssh/* routes only trust local loopback connections (socket address must match IPv4 127/8 / ::1 / IPv4-mapped ::ffff:127/8, plus same-origin Host header check, sec-fetch-site / Origin), LAN neighbors get direct 403. WebSocket terminal upgrade also goes through the same loopback fence; local port forwarding tunnel only listens on 127.0.0.1, never exposed to external network. See src/routes.ts:42-62, src/engine.ts:709.

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

A: No. The Agent can only operate on host aliases already configured in GUI or imported from ~/.ssh/config. Tools like ssh_exec / ssh_upload will directly error if the alias is not configured, never fabricate hosts. This agreement is also written in the system prompt "Constraints" section (src/index.ts:58) and README.

Q: Will remote output be sanitized? Like env command?

A: No. stdout/stderr from exec / cluster is returned as-is (no secret replacement), commands like env may bring back remote environment variables with secrets into the conversation history. This is the same semantics as ssh-skill - transmission/execution consumes real remote resources, user confirmation needed before Agent uses.

Q: Can I download whole directories? How about upload?

A: Download only supports single file (select file in the remote browser in the "Transfer" panel, then go through /api/dsh-ssh/download); upload supports local directory recursion (files transferred one by one after walk), whole directory download not implemented. Limitations in src/engine.ts:519-533, README.md:74.

Q: Can I use aliases from ~/.ssh/config for jump hosts?

A: No. Each hop in the ProxyJump chain must be a host alias configured in this plugin (cannot cross-plugin reference ~/.ssh/config aliases); when importing, if a hop is not in this plugin's host table, it will error and skip during creation. Limitation in README.md:76, src/store.ts:240-260.

Q: Will auto-replay replay my commands?

A: Yes. When exec disconnects, it auto-reconnects (max 3 times), command will be resent on new connection; non-idempotent commands (like rm, appending to files) will have side effects, please use idempotent commands first or confirm before executing. See src/engine.ts:212-231, README.md:75.

Getting Started Difficulty

Beginner - one command install, restart dsh web to see SSH entry; hosts can be manually entered in GUI or one-click imported from ~/.ssh/config, no config files or command line needed. However, since it involves remote hosts, keys, and jump hosts, recommended to try 1-2 exec/tunnel commands before batch usage.

Known Issues & Limitations

  • Upload remote target path must be absolute path, relative paths are rejected (src/engine.ts:486-490, README.md:73)
  • Download only supports single file; upload supports local directory recursion (files transferred one by one after walk), whole directory download not implemented (README.md:74, src/engine.ts:519-533)
  • exec auto-reconnect on disconnect (max 3 times) will resend same command, non-idempotent commands need to pay attention to side effects (src/engine.ts:212-231, README.md:75)
  • Each hop in ProxyJump chain must be a host alias configured in this plugin, cannot cross-plugin reference ~/.ssh/config aliases (README.md:76)
  • Resume (断点续传) not yet implemented; single upload request body cap 4 GiB (src/routes.ts:23-26)
  • Agent tool transfer paths are the host machine's local paths (same semantics as ssh-skill) - ssh_upload / ssh_download directly read/write any local path with host process permissions, not through bash sandbox, please note this permission surface (README.md:30-31, src/index.ts:58)
  • Host configuration ~/.dsh/dsh-ssh.json stores passwords and passphrases in plaintext, file 0600, directory 0700, no encryption (src/store.ts:328-336, README.md:25-26)
  • exec / cluster remote output returned as-is (not sanitized), commands like env may bring back remote environment keys (src/index.ts:58, README.md:32-33)
  • Local port forwarding tunnel only listens on 127.0.0.1, external network cannot access; this is fence design, not a configurable option (src/engine.ts:709, src/routes.ts:42-62)
  • Host aliases only allow letters, numbers, dots ., hyphens -, underscores _ (first character cannot be separator); non-conforming regex will error and skip during creation/import (src/store.ts:62-68, src/store.ts:296-303)
  • When config file is corrupted, it is renamed to .corrupt-<timestamp> backup, then starts with empty table, will not be silently overwritten (src/store.ts:317-325)

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/CAPTAIN1275/dsh-ui-web/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