Introduction¶

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. When debugging agents in a Web UI environment or executing local commands, a real terminal is essential. The dsh-terminal plugin uses node-pty on the host side and xterm.js on the client side to provide an out-of-the-box interactive shell panel for the Web UI.

What Is This¶

dsh-terminal is a Web UI terminal panel plugin for DeepSeek Harness. It is maintained by giiiiiithub and released under the MIT License.

The plugin consists of host-side and client-side components. The host side uses node-pty to launch a real shell within the DSH service process (via ConPTY on Windows), while the client side uses xterm.js for rendering, providing a full-featured browser terminal experience.

Core Features¶

• Real PTY: Based on node-pty, it provides a real shell environment rather than a simple emulator.
• Browser rendering: Uses xterm.js (@xterm/xterm 6), supporting full color, cursor, scrollback (5000 lines), and Ctrl+Shift+C/V copy/paste.
• Multi-tab sessions: Supports opening multiple terminal tabs simultaneously. After collapsing the panel, host-side sessions continue running.
• Window interaction: Supports docked mode (height adjustable by dragging edges) and floating mode (movable window with eight-way resizing).
• Opens with project: The first session starts by default in DSH’s first workspace path; if not found, it falls back to the configuration directory or user home directory.

Installation and Enablement¶

Before installation, ensure that DeepSeek Harness is installed and dsh web starts normally. In addition, DSH profiles use pnpm to manage dependencies, requiring pnpm >= 9.

Step 1: Install¶

Run the following command in the DSH profile directory:

dsh plugin --profile web add dsh-terminal

Note: If the installation environment uses pnpm >= 10, it may block the build script for node-pty. In this case, add node-pty to the allowBuilds configuration in the profile directory’s pnpm-workspace.yaml, then rerun the installation command.

Step 2: Restart the Service¶

The plugin includes host-side code, so the dsh web process must be restarted for it to be loaded:

# 停止当前进程（如 Ctrl+C），然后启动
dsh web

Step 3: Verify¶

Refresh the browser page. After the >_ terminal button appears in the session header, click it to expand. The first expansion automatically starts a default shell session (cmd.exe on Windows).

Configuration¶

Default configuration can be overridden via cordis.patch.yml in the profile directory. Configuration items are applied after the plugin bundle layer.

- id: terminal
  config:
    shell: cmd.exe          # 默认 shell（Windows 下默认即 cmd.exe，也可填完整路径）
    cwd: <工作目录>           # 新会话默认工作目录
    env:                     # 追加到进程环境
      LANG: "zh_CN.UTF-8"

Known Limitations¶

• Session management: The active session limit is 64. When exceeded, the open operation first evicts exited sessions; if still full, it returns a session-limit error. Exited sessions are retained on the host for 60 seconds for reading exit codes, then moved to tombstone (limit 64 entries).
• Service restart: Restarting the DSH service terminates all PTY sessions.
• Kill command: The kill command behaves differently on Windows and Linux. On Windows, it first uses taskkill to force clean up the process tree, then performs normal termination via node-pty; on Linux, it terminates by process group. Residual processes may remain only in special cases, such as when a child process is started with CREATE_NEW_CONSOLE.
• Collapsed panel: Session output for collapsed panels or inactive tabs is buffered on the host (limit 2MB) and replayed at once upon reactivation.

Conclusion¶

The dsh-terminal plugin addresses the pain points of debugging and command execution in a Web UI environment, providing a real, low-latency terminal experience. By configuring shell, cwd, and env, it can be adapted to different development scenarios.

For more details, refer to the plugin catalog or the GitHub repository.