Introduction

In DeepSeek Harness (DSH) development scenarios, agents often need to access remote servers for deployment, debugging, or data interaction. dsh-ssh-tunnel is a community plugin designed to address permission management, session maintenance, and interactive UI challenges for multi-host SSH access. It provides an SSHManager tool for dsh-better-sidebar and implements multi-host tunnel management.

Plugin Positioning

  • Name: dsh-ssh-tunnel
  • Type: DeepSeek Harness community plugin
  • Maintainer: thirsty5034
  • Positioning: Multi-host SSH tunnels + SSHManager tool
  • Compatibility: For dsh-better-sidebar (>= 0.12)

Core Capabilities

This plugin provides a complete SSH management mechanism with the following core capabilities:

  1. Host Inventory and Secrets Management: Maintains a local host inventory (hosts.json) and secrets (secrets.json). This sensitive information is not exposed to models and is used only for internal plugin processing.
  2. Project-Scoped Authorization: Supports project-based permission control. Using projectPathKey (typically the workspace directory), it associates an accessible host list to enable fine-grained access control.
  3. Model Tool SSHManager: Provides a standardized tool interface for models. It supports operations such as exec (execute commands) and sftp_list (list files), and supports session policies (such as reusing or creating a new session).
  4. Sidebar Management: Provides a sidebar tab for managing host CRUD operations, project authorization, and session connect/disconnect actions.
  5. Interactive Interface: Offers an interactive terminal (based on xterm) and a dual-panel SFTP file management interface in a central overlay.
  6. Non-Invasive Design: The plugin does not attempt to replace the global fs or subprocess with a single remote disk, preserving DSH’s original file system architecture.

Installation and Enablement

Installation via the official CLI source is recommended to ensure version compatibility with the DSH environment.

export DSH_HOME=${DSH_HOME:-$HOME/.dsh}
dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"

After installation, restart the DSH Web process and perform a hard refresh in the browser (Ctrl+Shift+R or Cmd+Shift+R) to load the new plugin interface.

Typical Usage

Models interact with remote hosts by invoking the SSHManager tool. The following are standard tool-call examples:

  • List all hosts:
    SSHManager action=list_hosts
  • Execute a command on a specified host:
    SSHManager action=exec host_id=<id> command="uname -a"
  • List a directory via SFTP:
    SSHManager action=sftp_list host_id=<id> path=/

Session Policies:
When invoking the tool, you can specify a session policy through parameters:
* reuse_or_create: Default policy; attempts to reuse an existing session and creates a new one if unavailable.
* new: Forces creation of a new session.
* require_existing: Uses only an existing session; errors if none exists.
* session_id: Explicitly specifies a session ID.

Data and Security

Plugin data is stored in the $DSH_HOME/ssh-tunnel/ directory (permissions are 0700):

  • hosts.json: Stores host metadata.
  • secrets.json: Stores passwords, PEM private keys, or passphrases (permissions are 0600).
  • grants.json: Stores mappings from project paths to lists of host IDs.
  • known_hosts.json: Stores verified host key fingerprints in SHA256 hexadecimal format.

Security Constraints:
* Authentication Methods: Only password or private-key authentication is supported. Keyboard-interactive authentication is deprecated; edit the host configuration to use password or private-key authentication instead. Bastion Web MFA is not supported.
* File Path Restrictions: Local upload, download, and listing operations are restricted to the /workspace directory. Lexical path checks and realpath checks are performed, and symbolic links are rejected.
* API Security: The HTTP API listens only on localhost and relies on trusted-hosts configuration. The browser Origin must match the configured values, and session APIs must provide projectPathKey.
* Key Rotation: If you suspect that secrets.json has been leaked, rotate the keys immediately.

Notes

  1. Does Not Replace the Global File System: The plugin provides session-level and tool-level SSH access; it does not change DSH’s global file system permission model.
  2. Dependency Environment: Ensure that DSH Web has dsh-better-sidebar (>= 0.12) configured and that Node.js is version 18 or later.
  3. Session Keepalive: The plugin includes an ssh2 keepalive mechanism (30-second interval). After an unexpected disconnection, it attempts automatic reconnection, with up to 3 retries.
  4. Frontend Dependencies: The terminal dependencies @xterm/xterm@5.5.0 and @xterm/addon-fit@0.11.0 are loaded through same-origin routing; there is no CDN fallback.

Summary

dsh-ssh-tunnel provides a standardized SSH management solution for the DSH ecosystem. Through project-level authorization and a model tool interface, it addresses security and usability pain points for multi-host remote operations. After configuring the host inventory and secrets, developers can directly use the SSHManager tool during conversations.