Introduction

DSH usually allows agents to read and write files in the server workspace. If the target files are on the local machine, common practices involve uploading, copying first, or relying on extra synchronization methods; after DSH finishes modifying them, the results need to be transferred back to the local machine.

dsh-local-project addresses this scenario: it imports a local folder as a DSH workspace on the server and synchronizes DSH’s modifications to the server image back to the local folder.

What is it

dsh-local-project is a DSH plugin maintained by 0xKcyzz, licensed under the MIT license.

Its positioning is: users select a local folder in the browser, and DSH creates a corresponding workspace image on the server side; thereafter, DSH uses native tools to directly manipulate the server image and synchronize file changes back to the local machine.

Core Features

Below are several verified capabilities:

  • Select a local folder via the “Add Workspace” entry, automatically upload it, and create a mirrored workspace on the server.
  • DSH uses native read, write, edit, glob, and bash tools to directly manipulate the server image, without needing custom tools.
  • After DSH modifies a file, it synchronizes back to the local machine in real-time via WebSocket.
  • After a WebSocket disconnection, it automatically reconnects and catches up on missed changes.
  • “Delete Project” only deletes the server copy and workspace record, without affecting local files.
  • After refreshing the page, you can restore the project list from the server and re-select the local folder to resume synchronization.
  • The plugin provides /local-project/* HTTP interfaces and WebSocket pushes, supporting creation, upload, listing, download, deletion, and change restoration.

Installation and Activation

First, execute the official installation command:

dsh plugin --profile web add github:0xKcyzz/dsh-local-project

After installation, DSH needs to be restarted. After restarting, “Add Workspace” will open the local project import dialog.

If the server image directory for the local project does not use the default location, you can configure the environment variable:

DSH_LOCAL_PROJECT_ROOT
Default: $DSH_HOME/workspaces

Typical Usage

Below is a reproducible usage workflow:

  1. Click “Add Workspace” in the DSH sidebar or empty state.
  2. Enter a project name and click “Select folder and import”.
  3. Select a local folder in the system dialog. This step requires authorization from Chrome/Edge browsers.
  4. The first import will start uploading files. Once complete, “Local Project: Name” will appear in the left workspace list.
  5. Open the workspace conversation. DSH operates on the server image copy, and file changes are automatically synchronized back to the local machine.

Use Cases

Suitable for this usage pattern: handing over local code or materials to the remote DSH for direct read/write access in the browser while keeping a local copy.

It is more suitable for scenarios initiated by DSH. After DSH modifies a file in the server image, changes are pushed back to the local machine; local files that already exist can be uploaded to the server during the first import.

Notes

Note the following limitations before use:

  • Requires browser support for File System Access API: Chrome/Edge (including Chromium). Firefox/Safari are not supported.
  • Single file limit is approximately 15MB, upload uses base64 JSON. Large files are not recommended for inclusion in the project.
  • Deletion of individual files is not propagated: only “Delete Project” will delete the entire package copy on the server. Files deleted locally and on the server individually will not be cleared by the other side.
  • Local changes are not automatically uploaded: only the first import uploads local files. Manually modified files locally after the first import will not be synchronized to the server.
  • Real-time push requires maintaining a WebSocket connection. It will automatically reconnect after disconnection and catch up on missed changes.
  • If File System Access API is unavailable in the desktop Electron window, please open DSH’s web address using a system browser.
  • The plugin loads with the DSH plugin mechanism and executes related operations with the permissions of the current DSH process. Source code and license should be checked before installation.

Links

GitHub Repository: https://github.com/0xKcyzz/dsh-local-project