Skip to main content

dsh-remote

31Stars8Forks3Issues0Watchers

DSH Remote Workspace Assistant: Saves multiple SSH hosts, mirrors remote directories to local workspace, enabling Agent to directly read/write remote files, run commands, and forward ports.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
License
MIT
Branch
main
deepseek-harnessdshdsh-pluginremotesftpsshtunnelworkspace

Install

cmdweb profile
$ dsh plugin --profile web add dsh-remote

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 flymysql/dsh-remote for me: review the repository at https://github.com/flymysql/dsh-remote 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 Description

Extends DSH's workspace from "local directory" to "any directory on SSH hosts": save multiple hosts, one-click mirror remote directories as native DSH workspace, enabling Agents to operate remote files, run commands, and create tunnels across networks.

Core Capabilities

  • Multi-host SSH management: Save any number of hosts in "Settings → Remote Workspace" (host/port/user + private key or password), one-click switch current machine; supports private key passphrase, OpenSSH Agent, keyboard interaction (OTP/MFA), jump host (ProxyJump).
  • Remote workspace selector: Fills DSH native "Add workspace" flow, popup with "Local" and "Remote" tabs, defaults to local; after switching to remote, select machine and input/browse remote path to generate mirrored workspace.
  • 21 rw_* model tools: info / connect / pick_workspace / list_dir / stat / read_file / write_file / edit / append / mkdir / remove / move / exec / search / download / upload / sync / push / forward / disconnect; rw_exec can allocate PTY and set environment variables, rw_edit has mtime optimistic locking.
  • Bidirectional SFTP sync: rw_sync (remote→mirror) and rw_push (mirror→remote) use three-way comparison, detect conflicts without overwriting, supports dryRun preview, async background run, force override; default has single file size limit, ignore rules (gitignore syntax).
  • SSH port forwarding: Local forward and remote reverse tunnels, add/delete/start/stop in settings panel or rw_forward; saved to forwards.json, supports auto-reconnect, stops when connection disconnects.
  • Host fingerprint TOFU verification: Record fingerprint on first connection to known_hosts.json, subsequently reject fingerprint changes; provides accept-new / verify / off three modes.
  • Sidebar remote files: Built-in dsh-better-sidebar, provides "Remote Files" directory tree + visual editor (includes "Edit → Save to Remote" flow with mtime optimistic lock protection, 409 prompt to reload).
  • Command audit log: All rw_exec / write / delete / move / forward operations appended to audit.log, recent entries viewable in settings panel.
  • Optional system keychain for password storage: When "Encrypt password" is checked, delegate single machine password to macOS Keychain / Windows DPAPI / Linux secret-tool, falls back to plaintext on failure.
  • Self-update: Pulls version from npm, supports "manual / auto / off" three modes, auto mode silently checks and upgrades at configurable intervals.
  • ~/.ssh/config import: Settings page lists SSH config Host records, one-click auto-fill form (only imports config paths, does not read private key content).

Technical Implementation

  • Language: JavaScript (ESM, Node.js)
  • Key dependencies: ssh2 (SSH/SFTP client, pure JS implementation without native bindings), @deepseek-ai/schemastery (config schema validation), dsh-better-sidebar (sidebar UI, v0.7.2+ hard dependency on embedded mount), iconv-lite (GBK and other non-UTF-8 encoding read/write)
  • Architecture pattern: Dual half-plugins: host half (lib/index.js) registers 21 tools, system-prompt sections, and 16 /dsh-remote/* JSON endpoints via Cordis inject=['tools','systemPrompt','webServer']; client half (lib/client.js) registers React UI via window.__ModuleLoader__ (settings page, remote workspace selector completion, sidebar entry), priority -100 fills directory-flow hooks. All file operations go through SFTP protocol layer, supporting both POSIX and Windows remotes.
  • Entry files: lib/index.js (host half) + lib/client.js (client half), paired with cordis.patch.yml (auto-inserts main and sidebar lines)

Use Cases

Use cases requiring DSH Agent to operate code and commands on remote development/deployment/internal servers: typical scenarios are when local editing is inconvenient or files only exist remotely; mirror remote directories as DSH real workspace for remote build/deployment, ops checks, cross-network collaboration. Suitable for users who need to switch between multiple machines, use private keys or passwords, jump into internal networks, or temporarily create several SSH tunnels.

Prerequisites & Compatibility

DependencyMinimum VersionDescription
DSH (DeepSeek Harness)^0.1.0-rc.6Declared in package peerDependencies, requires @deepseek-ai/dsh-commands / @deepseek-ai/dsh-host-webserver / @deepseek-ai/dsh-tools / @deepseek-ai/dsh-system-prompt / two client runtime packages with same version number
Node.jsNot declaredRepository does not set engines, but code uses newer interfaces like node:zlib zstd, node:fs/promises, recommend using current LTS
PlatformmacOS / Windows / LinuxClient, host, and remote all cross-platform; remote read/write uses SFTP protocol layer, not shell-dependent
Native modulesNonessh2, iconv-lite, schemastery, dsh-better-sidebar are all pure JS
pnpm linkerhoistedProfile's pnpm-workspace.yaml must keep nodeLinker: hoisted, otherwise embedded sidebar line cannot resolve dsh-better-sidebar (README.zh.md:61)

Installation

dsh plugin --profile web add github:flymysql/dsh-remote

Configuration Options

This plugin requires no manual configuration during installation; on first use, add hosts via the graphical interface in "Settings → Remote Workspace". cordis.patch.yml can also declare one default host (see README §"Optional: CLI Default Machine"). Schema fields (lib/index.js:55) are explained as follows:

ConfigTypeDescriptionDefault
hoststringSSH address of current host; empty string means plugin stays disconnected after startup''
portinteger 1–65535SSH port22
usernamestringLogin username''
passwordstringPassword (takes priority over private key when non-empty); actual value not stored here when triggering OS keychain''
privateKeyPathstringPrivate key path (only used when explicitly provided, never auto-read from ~/.ssh)''
passphrasestringPassphrase for encrypted private key''
workspacestringDefault remote workspace absolute path''
commandTimeoutMsinteger ≥ 1000Single remote command timeout (milliseconds)20000
connectTimeoutMsinteger ≥ 1000SSH connection establishment timeout (milliseconds)15000
maxOutputCharsinteger ≥ 1024Maximum collected output for single remote command200000
maxFileBytesinteger ≥ 0Skip files larger than this size during mirror sync, 0 = unlimited52428800 (50 MB)
hostKeyModestringaccept-new (trust on first use) / verify (reject unknown hosts) / off (disable, not recommended)accept-new
useAgentbooleanUse OpenSSH Agent on SSH_AUTH_SOCK (enabled when no password/private key)false
keyboardInteractivebooleanAllow keyboard interactive authentication (OTP/MFA chain), use local password to respondfalse
proxyobjectJump host/bastion {host, port, username, password, privateKeyPath}; empty host means not usedempty object
autoPushbooleanAutomatically push local mirror changes back to remote (3s debounce, filter ignore rules and three-way conflicts)false
auditLogbooleanLog each exec/write/delete/move/forward to audit.logtrue
encodingstringRemote text read/write encoding (default utf-8, can be gbk etc.)utf-8
updateModestringmanual (manual) / auto (check and auto-upgrade on startup + periodic) / off (disable)manual
updateCheckIntervalMsinteger ≥ 60000Interval to check npm registry in auto mode (milliseconds)21600000 (6 hours)

Additional: The host list in settings also has form fields for "privateKeyPath / passphrase / SSH Agent / jump host / encrypt password" (see settings page for details), each record can independently override the above fields.

FAQ

Q: How to switch between multiple machines?

A: Click "Set as Current" on any machine in the "Settings → Remote Workspace" list; after switching, that machine's workspace and port forwarding activate; rw_* tools also operate on the current machine. You can also use Model's rw_connect in tool calls to temporarily switch machines (save=false means not writing to the list).

Q: Which local folder does the remote workspace map to? Can I move it?

A: Default is $DSH_HOME/remote-workspaces/<host>-<user>-<port>/<basename>; when <basename> duplicates, a short hash is appended. Deleting this directory only deletes the local mirror, not the remote; if found at the old location before migration (~/.dsh/remote-workspaces), it auto-overwrites. To customize mirror location, use rw_download with explicit localPath= to download single files to any location.

Q: Can I change SSH private key/password mid-flight? Do I need to restart after changes?

A: No restart needed. After saving settings changes → triggers applyActiveMachine, underlying SshPool.setTarget bumps epoch and drops old connections; next tool call establishes new connection with new credentials; current active SSH connection immediately becomes invalid.

Q: Are port forwards preserved after restarting harness?

A: Defined in forwards.json, persisted permanently; forwards with "Auto-start" checked are automatically pulled up after each connection establishment.

Q: What happens if both sides are modified during sync?

A: Marked as conflict and both sides preserved without overwrite, console reports conflict paths and reasons; add force=true in UI or tool call to forcibly override remote with local (rw_push) or vice versa (rw_sync).

Q: Error "no host + workspace configured — call rw_connect with a host to get started" means what?

A: Plugin has no host configuration; add a host in settings page, or temporarily connect one via rw_connect in tool call.

Q: Can I reuse config from ~/.ssh/config?

A: Yes. Settings page has "Import SSH Config" button, one-click auto-fill Host/HostName/User/Port/IdentityFile/ProxyJump; only imports path references, does not read any private key content.

Q: Where are end-to-end security risks?

A: Entrusting machine credentials to this plugin means allowing Agent to run shell commands as you on the remote; only add machines you trust, and treat audit.log as sensitive data; you can tighten ACLs at filesystem level (audit.log / machines.json / .secrets/). All remote commands go through shell-escaping, cd working directory also uses shq quoting, single quotes passed through without expansion.

Learning Curve

Beginner — Add host, select workspace, ready to use; common configurations (password/private key/Agent/jump host) have UI forms, model tool calls also use natural language verbs like rw_list_dir / rw_read_file. Advanced features (auto-sync, port forwarding, TOFU strategy) work with defaults.

Known Issues & Limitations

  • Local directory selector on some Linux distributions depends on zenity / kdialog in desktop sessions; in pure CLI environments (no dbus), it reports ENOENT, you can manually fill path in input box (lib/index.js:1797-1819).
  • When SSH channel is silently closed by server due to idle, occasional Channel open failure: open failed may occur; starting from 0.7.3, it automatically invalidates old connections and reconnects once. If still occasional, increase keepalive/connectTimeoutMs or actively call rw_disconnect (lib/index.js:516-523).
  • Sync/search has file size limits (default 50 MB) and max file counts (sync 2000, search 500/2000) to avoid accidentally pulling large files; can set maxFileBytes=0 to disable size limit, but don't point sync task to repositories containing databases or large binaries.
  • audit.log appends in single process, no rotation, long-term use requires external logrotate.
  • 0.8.6 fixes hardcoded version number at bottom of settings page (previously any version showed v0.8.3).
  • 0.8.4 fixes startup crash when dsh 0.1.0-rc.8 loads 0.8.3; after upgrading, please sync upgrade both.
  • Embedded dsh-better-sidebar introduced in 0.7.2 requires profile's pnpm-workspace.yaml to keep nodeLinker: hoisted, otherwise embedded line cannot resolve same-named package (cordis.patch.yml:5-18 / README.zh.md:61).

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/flymysql/dsh-remote)

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