The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” When developing agents on the Web, if you need the model to execute Shell commands directly and maintain session state, traditional approaches often require switching to a local terminal. The dsh-interactive-terminal plugin solves this fragmentation by embedding a persistent PTY terminal in the browser, enabling interaction between the model and the user within the same interface.

Plugin Positioning

This is a client-side plugin developed by the maintainer mingzhicode. It uses xterm.js to render a terminal in the DeepSeek Harness Web interface, allowing an Agent to run programs through tool calls (shared_terminal_send) and also supporting human users to take over control and continue interacting. The core goal of the plugin is to provide a single-Agent terminal control mechanism, ensuring that only one view can write to the terminal at a time, while other views remain read-only.

Core Features

  • Persistent Bash session: Runs a persistent Bash terminal in DSH Web. Collapsing the panel or reconnecting after a disconnection does not terminate the Shell.
  • Shared by model and user: The model can run programs through tool calls, and human users can take over and continue interacting.
  • Based on xterm.js: Uses a standard Web terminal UI for rendering.
  • Single-controller mechanism: Only one browser view can control the Agent’s terminal; other views are read-only.
  • State recovery: Supports PTY screen snapshot recovery and reconnection after disconnection.

Installation and Enablement

Installation and startup must use the same DSH_HOME (defaults to ~/.dsh).

Prerequisites:
* Operating system: macOS or Linux
* Shell: Bash
* Tooling: Node.js (^22.19 || >=24), pnpm (must be available in PATH, version 10.18.3)
* DSH version: 0.1.0-rc.8

Installation steps:

  1. Run the following command in the terminal to install the plugin package into the Web profile configuration:
    dsh plugin --profile web add dsh-interactive-terminal@0.1.0
  1. Start DeepSeek Harness Web:
    dsh --profile web

  1. Open the printed URL in your browser. After configuring the model and session, click Open terminal.

  2. At an idle prompt, type echo hello to verify browser input.

Interaction Flow

After the plugin takes over the terminal, there is an explicit control-handoff logic:

  1. Open the terminal: Click Open terminal. The Shell is created lazily on first expansion or when the Agent invokes the tool.
  2. Confirm controller: Confirm that the status is shown as Controller. If you type directly at an idle prompt, the first key press requests human input ownership, and subsequent key presses wait for authorization.
  3. Model execution: The model invokes shared_terminal_send to run a program. At this point, the model owns the operation queue, and normal keyboard input is ignored.
  4. Take over input: When the program requests input, click Take over input and wait for authorization before typing. This takeover preserves the process, does not send a signal, and removes the model’s operation timeout.
  5. Continue interacting: Continue typing text, newlines, or UTF-8 characters in the same PTY. A newline submits input but does not release ownership until the Shell prompt is confirmed or the process exits.
  6. Interrupt: Use Interrupt input to send SIGINT. This interrupts the program and retains ownership until the prompt returns.

Configuration

The plugin supports overriding default behavior through a configuration file. The configuration file path is ~/.dsh/profiles/web/cordis.patch.yml (or a custom $DSH_HOME/profiles/web/cordis.patch.yml).

Configuration example:

- id: dsh-interactive-terminal
  config:
    shellPath: /bin/bash
    shellArgs: [--noprofile, --norc, -i]
    rows: 40
    cols: 160

After applying the configuration, DSH must be restarted. The following table lists the configurable fields, their default values, and effects:

Field Default Effect
shellPath /bin/bash Bash executable. Only Bash is supported; other Shells are rejected.
shellArgs --noprofile --norc -i Interactive Shell arguments. Empty arguments are rejected.
rows 40 Fixed number of rows generated for each PTY.
cols 160 Fixed number of columns for each PTY.
scrollbackLines 10000 Number of history lines retained outside the viewport.
scrollbackMaxBytes 4194304 Byte limit for serialized ANSI history.
maxToolOutputBytes 262144 Complete limit for tool result JSON.
maxInputBytes 65536 Byte limit for each human input lease sent or accepted by the model.
maxQueuedOperations 128 Number of changes allowed per Agent, including the current operation.
maxSessions 32 Maximum number of active Agent terminals.
pollIntervalMs 50 Polling interval for foreground process checks.
operationTimeoutMs 30000 Timeout for model changes.
interruptTimeoutMs 5000 Controlled prompt recovery timeout after SIGINT.
disconnectGraceMs 15000 Grace period before restoring the connection.
disposeGraceMs 3000 Process tree termination grace period during reset or cleanup.

Notes

  • Environment consistency: Installation and startup must use the same DSH_HOME; otherwise, the plugin may fail to load.
  • Dependency check: If pnpm reports that no version is available, check whether the public registry is being used (for example, registry.npmjs.org).
  • View limit: Only one browser view can control the Agent’s terminal at a time; other views and mobile views are read-only. To take over, you must close the current controlling view and reconnect after disconnectGraceMs.
  • Updates: After changing the configuration file, restart DSH for the changes to take effect.

Summary

dsh-interactive-terminal provides a standardized terminal interaction solution for the DSH ecosystem. Through a shared PTY and fine-grained input control logic, it brings the model’s automated operations in the Web interface closer to a real terminal experience, while also giving developers flexible configuration options.