Introduction

When developing with dsh web, you often need to execute a few commands directly in the browser. There are two common approaches: switching to a separate terminal window, or using an overlay terminal to cover the session content. The former requires constant context switching, while the latter obscures the ongoing conversation.

The dsh-web-shell introduced below adopts a third approach: dock the terminal on the right side of the window. The main chat bar automatically yields space, allowing the terminal and session content to be visible simultaneously, and the collapsible panel does not interrupt the session.

What is it

dsh-web-shell is a right-docked Web Shell plugin for DeepSeek Harness, maintained by JesmonX, released under the MIT license, with the current npm version being 0.1.1. The browser side uses xterm.js to render the terminal, bridging to the host-side PTY via the /api/shell WebSocket, supporting switching between bash and zsh.

DSH’s philosophy is “everything is a plugin”; this type of UI extension connects to the host via the plugin mechanism.

Core Features

According to the README description, the plugin provides the following capabilities:

  1. Right Docking. Upon opening, the main chat bar automatically yields space and no longer obscures the session content. The full effect requires a relatively new dsh-client-ui-layout; older host versions will automatically downgrade (see the Compatibility section below).

  2. Resizable Width. Drag the left edge of the shell to adjust, with a range of 360–960px.

  3. Profile-Based Layout Memory. The settings domain of the current profile saves the dock width and folded state, which is restored after a refresh. Specifically, the plugin registers a web-shell settings namespace with fields dockWidth and folded; the width is only written when the drag ends, and both folding and closing are recorded as folded. Settings do not use browser localStorage, so reloading the same profile will not lose layout preferences.

  4. Fold and Close Separation. Folding hides the panel but keeps the WebSocket / PTY session alive, restoring the same shell upon expansion; closing disconnects the connection and terminates the PTY, creating a new shell upon reopening.

  5. Bash / Zsh Switching. Switching closes the old PTY and starts a new shell.

  6. Security Pre-check Companion. The plugin also publishes dsh-web-shell/invariant, exporting checkWebShellTrust(), which performs pre-check security fence checks on the /api/shell upgrade route before startup.

Installation and Enabling

Requirements: DeepSeek Harness >= 0.1.0-rc.5 (the latest on npm @deepseek-ai/dsh is 0.1.0-rc.6).

First, install from npm (recommended):

dsh plugin --profile web add dsh-web-shell

Start after installation:

dsh web

Click the ❯_ button on the right side of the window to open the shell.

You can also install from GitHub:

dsh plugin --profile web add github:JesmonX/dsh-web-shell

The repository has committed the built lib/, so a direct git installation works without the need for build authorization. If your plugin manager does not support the GitHub shorthand, you can clone it first and then install locally:

git clone https://github.com/JesmonX/dsh-web-shell.git
dsh plugin --profile web add ./dsh-web-shell

Typical Usage

Daily operations focus on the panel buttons and edge dragging:

  • Open / Expand: The ❯_ button on the right, to open the shell or restore it from a folded state.
  • Fold: The › button on the panel title bar, to hide the panel while keeping the session alive.
  • Close: The × button on the panel title bar, to terminate the session.
  • Switch Shell: bash / zsh on the title bar, to start a new PTY.
  • Adjust Width: Drag the left edge of the panel, with a range of 360–960px.

Host-side default configuration is injected via cordis.patch.yml:

- id: web-shell
  name: 'dsh-web-shell'
  inject: [webServer, subprocess, webRuntime]
  config:
    shells: [bash, zsh]
    defaultShell: bash
    rows: 40
    cols: 120
    graceMs: 5000
    fontFamily: '"Maple Mono NF CN", "Sarasa Mono SC", "Cascadia Code", "JetBrains Mono", "Noto Sans Mono CJK SC", "Microsoft YaHei UI", monospace'

The meaning of each field is as follows, and all can be overridden in subsequent patch layers:

  • shells: Optional list of shells, currently supports bash and zsh.
  • defaultShell: The default shell used when no shell is selected in the browser.
  • cwd: The starting directory for the new terminal, defaults to process.cwd().
  • rows / cols: The initial number of terminal rows and columns.
  • graceMs: The grace period for PTY cleanup.
  • fontFamily: The CSS font stack for xterm.js in the browser, using fonts from the browser’s system.

Compatibility

The plugin’s shell.overlay slot is declared by dsh-client-ui-layout. The full “main chat bar yielding space” effect relies on this package providing APIs such as ctx.layout.setShellWidth / closeShell for right-side docking.

If the host UI version is older (has shell.overlay but not the right-side docking APIs), the plugin will automatically downgrade to a pure overlay mode: the shell can still be opened, folded, closed, and dragged, but the main chat bar will not yield space.

Security and Considerations

First, regarding permissions: the shell runs with the same operating system permissions as the dsh process. Before installing into your environment, you should check the plugin source code and license to ensure it is acceptable before use. The plugin uses the MIT license, and the source code is public on GitHub.

Next, network security. The /api/shell upgrade route uses the same loopback / trusted-host / origin protection as the /api gateway; non-loopback deployments must explicitly declare trustedHosts.

If you want to discover configuration gaps before startup, you can hook into the dsh-web-shell/invariant companion. It exports checkWebShellTrust(), which performs the same set of /api/shell fence pre-checks on the parsed webServer / webRuntime configuration within the invariant/doctor diagnostic combination in dsh: the Host must exist, loopback must be available, non-loopback Hosts must be in trustedHosts, the Origin must be same-origin, and Sec-Fetch-Site: cross-site must be rejected; when binding to 0.0.0.0, at least one valid trusted host must be configured. This exposes issues before startup rather than after the WebSocket upgrade.

Conclusion

Following the steps above, you will have a browser terminal that does not obscure the session, folds without disconnecting, and remembers the layout based on the profile. For developers who frequently operate DSH in the browser, this is a plugin worth installing and trying.

Plugin Directory Page: https://www.skillhub.cn/plugins/JesmonX/dsh-web-shell

GitHub Repository: https://github.com/JesmonX/dsh-web-shell

It should be noted that skillhub.cn is a community-maintained independent plugin directory with no official affiliation to DeepSeek or High-Flyer.