Hefulalala/dsh-remote-workspace

A plugin for DSH that brings SSH/SFTP remote workspaces into the workspace sidebar — alongside your local directories.

• Remote site = one SSH/SFTP connection profile (host / user / auth / home directory), managed from the 🌐 Remote Sites button.
• Remote workspace = a remote site + a directory on that server. It appears in the left workspace tree exactly like a local workspace, owns its own sessions, and lets the agent read/write remote files directly.
• Unified "Add Workspace" flow — the same add-workspace entry point now asks you to choose a connection first: Local (this computer) or one of your remote sites.

---

中文速览

• 远程站点：SSH/SFTP 连接配置（主机 / 用户 / 认证 / 家目录），左下角“🌐 远程站点”管理。
• 远程工作区：远程站点 + 远程目录；和本地目录一样出现在左侧栏、按工作区分组 session。
• 统一添加入口：左侧栏“添加工作区”先选连接（本地 / 远程站点 / 新建站点），再选目录。
• 默认家目录：站点配置中目录留空时，自动通过 SFTP 解析服务器真实 home。
• Agent 工具：remote_site_* 管理连接，remote_workspace_* 在会话中直接读写远程文件。

---

Features

• Site management (bottom-left panel)

  • Add / edit / test / delete SSH/SFTP connection profiles
  • Auth modes: password, private key file (host path), or SSH Agent
  • Empty home path is resolved via SFTP realpath('.') to the server's real home

• Unified add-workspace flow (left sidebar)

  • Step 1 — choose connection: local computer, an existing remote site, or create a new site
  • Step 2 — choose directory:
    • Local → native-style directory browser (breadcrumbs, enter folders, create folder)
    • Remote → SFTP directory browser starting at the site home; supports navigation and folder creation
  • One site can host multiple remote workspaces

• Native workspace/session grouping

  • Each remote workspace gets a local anchor directory ($DSH_HOME/remote-workspaces/<id>/)
  • The anchor is registered into DSH's workspaceRegistry, so remote workspaces appear and behave like local ones: click to start a session, session history stays grouped
  • AGENTS.md is generated in the anchor: the agent learns the real remote endpoint/root and routes file operations through remote_workspace_* tools

• Agent tools

  • remote_site_list / add / test / rename / update / remove / browse
  • remote_workspace_list / add / browse / read / write / test / remove
  • Path traversal protection (everything is confined to the workspace root), read/write size limits

• Security

  • SSH host-key TOFU: first connection records sha256:<fingerprint>, later connections reject mismatches
  • Config is persisted in $DSH_HOME/storages/remote-workspaces.json with 0600 permissions
  • Deleting sites/workspaces never deletes remote files; session logs are preserved

---

Install

The package declares a dsh.bundle manifest, so it is installable through DSH's plugin command and by plugin storefronts such as dsh-market.

Option A — GitHub Release tarball (recommended)

1. Download dsh-external-dsh-remote-workspace-0.1.0.tgz from the Releases page.

2. Extract and prepare it:

   mkdir -p ~/dsh-plugins
   tar -xzf dsh-external-dsh-remote-workspace-0.1.0.tgz -C ~/dsh-plugins
   bash ~/dsh-plugins/package/install.sh   # installs ssh2 and validates artifacts
   

3. Inject it from your DSH session:

   # DSH injector environment:
   #   dev_inject_plugin ~/dsh-plugins/package
   

4. Refresh the DSH web page.

Option B — DSH plugin manager

The repo ships dsh.bundle.patch + cordis.patch.yml, so a DSH install that supports bundle installation can add it directly:

dsh plugin --profile web add Hefulalala/dsh-remote-workspace

Option C — build from source

git clone https://github.com/Hefulalala/dsh-remote-workspace.git dsh-remote-workspace
cd dsh-remote-workspace

# Install the runtime dependency (and, if you want local builds, the toolchain):
npm install --omit=dev ssh2
npm install --save-dev typescript tsdown @types/node @types/react @types/react-dom @types/ssh2

bash scripts/build.sh        # host: src/index.ts → lib/
npm run build:client         # client: src/client/index.tsx → lib/client.js

# In the DSH injector environment:
#   dev_inject_plugin /absolute/path/to/dsh-remote-workspace

scripts/build.sh auto-detects a DSH source checkout (DSH_CHECKOUT) for peer-type linking; otherwise it falls back to the locally installed toolchain.

---

Usage

1. Open 🌐 Remote Sites in the bottom-left sidebar and add a site:

   Field	Notes
   Host / Port / Username	SSH target
   Home directory	optional; empty = auto-detect the remote home
   Auth	password / private-key file / SSH agent

2. Click Add Workspace in the left workspace tree:

   • Choose Local → pick a local folder (same as before)
   • Choose a remote site → pick a remote folder (starts at the site home)
   • Choose New remote site → configure the connection, then continue to folder selection

3. A remote workspace now appears in the left tree. Click it to open a new session, then just talk to the agent, e.g.:

   "Read /srv/app/config.yml and change the port to 8081"
   

The agent resolves paths against the remote root and uses remote_workspace_read/write automatically (guided by the generated AGENTS.md).

---

Security notes

• MVP storage: passwords and private-key passphrases are currently stored in plain text inside a 0600 JSON file. For production, wire the plugin to DSH's credentials service or an OS keyring.
• Private keys are never copied into the plugin store — only the host path is saved.
• Remote file APIs are same-origin and enforce workspace-root confinement (8 MB write cap, 2 MB default read cap).
• Host fingerprint changes cause the connection to be rejected (manual fix: edit the site / re-add).

---

Agent tools

Tool	Purpose
remote_site_list	List configured SSH/SFTP connection profiles
remote_site_add	Add a site (tests the connection; home defaults to the remote home)
remote_site_test	Test a site connection
remote_site_rename	Rename a site (auto-derived workspace names follow)
remote_site_update	Update connection/auth/home of a site
remote_site_remove	Remove a site and its workspace registrations
remote_site_browse	Browse site directories (workspace folder picking)
remote_workspace_list	List remote workspaces
remote_workspace_add	Create a workspace for siteId + rootPath
remote_workspace_browse	Browse a workspace directory
remote_workspace_read	Read a remote file (binary → base64)
remote_workspace_write	Overwrite a remote file (utf8/base64)
remote_workspace_append	Append to a remote file (no whole-file rewrite)
remote_workspace_write_at	Patch part of a remote file at a byte offset
remote_workspace_test	Test a workspace root
remote_workspace_remove	Remove the sidebar grouping only

---

Host HTTP API

Prefix: /remote-workspaces/api — every response is {ok:true,value} or {ok:false,error:{code,message}}.

Method	Route	Purpose
GET	/ping	Health check
GET	/sites/list	List sites
POST	/sites/add	Add site
POST	/sites/test	Test site
POST	/sites/rename	Rename site
POST	/sites/update	Update site
POST	/sites/remove	Remove site
POST	/sites/browse	Browse a site directory
POST	/sites/mkdir	Create a remote folder
GET	/workspaces/list	List remote workspaces
POST	/workspaces/add	Create remote workspace (siteId, optional rootPath, optional name)
POST	/workspaces/ensure	Ensure sidebar anchor exists
POST	/workspaces/rename	Rename workspace
POST	/workspaces/remove	Remove workspace
POST	/workspaces/test	Test workspace root
POST	/workspaces/browse	Browse workspace directory
POST	/workspaces/read	Read file (cached by mtime+size)
POST	/workspaces/write	Write file
POST	/workspaces/append	Append to a file
POST	/workspaces/writeat	Patch part of a file at a byte offset
GET	/pool-stats	Connection-pool and file-cache stats

---

Data model

$DSH_HOME/storages/remote-workspaces.json (v2):

• sites[] — connection profiles: host, port, user, auth, resolved homePath, host fingerprint
• workspaces[] — siteId + rootPath + sidebar anchor (localWorkspaceId)

Version 1 stores are migrated automatically on first load.

---

Development

src/index.ts             Host: data model, SSH2/SFTP, workspaceRegistry anchors, HTTP API, tools
src/client/index.tsx     Client: Remote Sites panel + unified add-workspace flow
cordis.patch.yml         dsh.bundle patch used by `dsh plugin add`
scripts/build.sh         Host build
scripts/smoke.mjs        Artifact smoke test
lib/                     Build output

More design details: docs/architecture.md · CHANGELOG.md.

• Host services required: webServer, tools, workspaceRegistry
• Client services required: slots, workspaces
• The client shadows DSH's built-in directory-flow slots at priority -1 and wraps local-picking behavior, so removing the plugin cleanly restores the built-in flow.

Known limitations

• Remote file editing happens through the agent tools; the site panel itself only manages connections
• Connections are pooled per site (idle TTL + auto-reconnect); hot-path file ops also get an mtime+size content cache
• No remote rename/delete, directory sync, or conflict handling yet
• Passwords are stored in plain text (see Security notes)

License

BSD-3-Clause © 2026 dsh-remote-workspace contributors. See LICENSE.