Introduction¶

When developing agents with the DSH Web GUI, a common annoyance is that there is only one workspace: code in one directory, datasets in another, and reference materials in a third. To make the agent work across these directories, you either have to manually move files into a single workspace or simply prevent the agent from touching them.

dsh-multi-root addresses this problem. Below is an introduction to this plugin: it adds a Roots (Multi-root) panel to the sidebar, allowing an arbitrary number of independent folders to be mounted as workspace roots, and then uses a set of controlled host-side tools to let the agent list/read/write/glob between these roots—the idea is similar to VS Code’s multi-root workspace.

What is This¶

dsh-multi-root is a multi-root workspace plugin for the DeepSeek Harness (DSH) Web GUI, maintained by luoyu-xingu, current version 0.1.1, MIT license.

It is activated in the web profile as a cordis profile bundle, hot-swappable, and does not require modifying DSH source code—this aligns with DSH’s “everything is a plugin” design. A few basic conventions are clarified first:

1. All roots are equal; there is no distinction of “primary workspace”; the root set is shared by all sessions and agents.
2. The GUI and the agent share the same root directory storage.
3. UI text is bilingual (zh/en), following the documentation language.

Core Features¶

Root Management¶

• Sidebar Roots (Multi-root) entry; clicking switches the center column to the management panel.
• Mount an arbitrary number of folders: you can enter paths directly or select via the host directory browser (Windows starts from drive level, Linux/macOS from home directory), each root can be configured with an optional display alias.
• Supports renaming, removing, and sorting roots; each line displays real-time directory status (available / directory missing).
• Roots are persisted in ~/.dsh/dsh-multi-root.json: directory permissions 0700, file permissions 0600, atomic writes.

Tools Registered for the Agent¶

The plugin registers five tools into the DSH tool pipeline, all restricted to operations within registered roots:

Announcement and Configuration for the Agent¶

The plugin adds a section to the system prompt to announce itself and the above tools to each agent; this can be turned off if desired. Host-side configuration is validated by schemastery, consisting of three items:

multi-root:
  enabled: true          # Master switch for routing, tools, and prompt sections
  announceToAgent: true  # System prompt announcement switch
  hotReload: true        # Host listens to its own lib/, remounts after rebuild

Installation and Activation¶

Recommended installation from npm, available on any platform:

# 1. Add the plugin to the web profile
dsh plugin --profile web add @luoyu_xingu/dsh-multi-root

# 2. Start the Web GUI (Ctrl+C to stop, --port to change default port)
dsh web

Open the address printed by dsh web, default is http://127.0.0.1:3080. The appearance of the Roots (Multi-root) entry in the sidebar indicates it is active; you can also verify installation with the following command:

dsh plugin --profile web ls @luoyu_xingu/dsh-multi-root

Upgrade and removal:

dsh plugin --profile web update @luoyu_xingu/dsh-multi-root
dsh web   # Restart after upgrade

dsh plugin --profile web remove @luoyu_xingu/dsh-multi-root

If you want to install from source:

git clone https://github.com/luoyu-xingu/dsh-multi-root.git
cd dsh-multi-root
pnpm install
pnpm build
# file: way to add the checked-out absolute path, profile saves a self-contained copy
dsh plugin --profile web add file:<checkout absolute path>
# Windows example:
dsh plugin --profile web add file:E:/dsh_plugins/dsh-multi-root

After modifying code and rebuilding, first sync the new lib/ into the self-contained copy in the profile, then restart:

pnpm build
# PowerShell:
Copy-Item lib\* $env:USERPROFILE\.dsh\profiles\web\node_modules\@luoyu_xingu\dsh-multi-root\lib\ -Recurse -Force
# bash:
cp -r lib/* ~/.dsh/profiles/web/node_modules/@luoyu_xingu/dsh-multi-root/lib/
dsh web   # Restart

One thing must be noted: dsh web must be restarted after installation or every rebuild. The web profile disables cordis HMR; file changes won’t hot load. The host also validates the bundle revision against the startup file hash, and old processes will return 404 for old revisions (bundle script ... failed to load).

Typical Usage¶

After the above steps, daily use is just three steps:

1. Click the sidebar Roots entry.
2. Mount folders using path input or the Browse dialog (Windows select drive first), assign aliases to each root as needed.
3. Directly let the agent work across folders—the agent will first use workspace_roots to discover roots, then use other workspace_root_* tools to operate within them.

If you want to participate in development, the repository provides three commands:

pnpm typecheck   # tsc -b + test tsconfig type checking
pnpm test        # vitest run
pnpm build       # declaration files + lib/ (node half and client bundle)

Security Model¶

This plugin deliberately bypasses DSH’s file sandbox: all operations run with host process permissions, and the trust boundary is the root set itself. Specific constraints are as follows:

• Roots can only be mounted by the user in the GUI; the agent can never mount or remove roots.
• Path escape prevention: All paths are concatenated relative to the root and normalized via fs.realpath, and must fall within registered roots; .., absolute paths, drive letters, and symlink escapes are all rejected during read/write, and the resolved parent directory is additionally validated during write; glob does not follow symlinks.
• Output limits: Read 256 KB, Write 5 MB, List Directory 500 entries, Glob results 1000 entries, ensuring the content the model receives is bounded.
• All /api/dsh-multi-root/* routes are restricted to loopback with browser same-origin flags; deployments exposed to LAN cannot access these routes.
• Stored files do not contain secrets, but are still written atomically with 0600 permissions.
• Known limitations: Tools run with host user permissions and occupy real disk space; before overwriting existing files, the agent must first confirm with the user; the directory browser will list host directories (designed to be loopback-only, it is the data source for the selector).

Applicable Scenarios and Precautions¶

The suitable scenarios are straightforward: files are originally scattered across multiple directories, you don’t want to move them into a single workspace for the agent, but you do want the agent to read and write within clearly defined scopes.

There are two things to clarify before use:

1. The plugin runs with the permissions of the current dsh process, essentially opening real disk read/write channels under these root directories for the agent. Which roots to mount and the scope of mounting are trust decisions you need to make.
2. It is recommended to check the source code and license before installation. The repository is published under MIT, and the code is public on GitHub; runtime environment requires Node ^22.19.0 || >=24.0.0, peer dependencies are @deepseek-ai/dsh-* ^0.1.0-rc.6 and react/react-dom ^18.2.0, plus fast-glob ^3.3.3.

Summary¶

dsh-multi-root fills the gap in DSH Web GUI for multi-workspaces with a single plugin: mounting and management are completed in the sidebar, agent-side access is controlled via five workspace_root_* tools, and path validation, output limits, and route restrictions are closed-loop within the plugin, requiring no modification of DSH source code throughout.

• GitHub: https://github.com/luoyu-xingu/dsh-multi-root
• Community Directory: https://www.skillhub.cn/plugins/luoyu-xingu/dsh-multi-root

It should be noted that the Community Directory is an independent site with no official affiliation with DeepSeek or Hypersphere.