📦 @goodandready/dsh-remote-workspace

---

⚡ Overview & The Problem

In modern software engineering and agentic workflows, AI agents orchestrating code within DeepSeek Harness (DSH) frequently need to work across remote environments: cloud virtual machines, high-performance GPU instances, containerized remote clusters, and staging servers.

Without @goodandready/dsh-remote-workspace, developers face critical roadblocks:

1. Local Boundary Limitation: Standard DSH operations and agent tools run exclusively against the local machine where DSH is deployed.
2. Fragile Ad-Hoc Scripts: Manual SSH wrappers and ad-hoc SCP uploads lack robust connection pooling, causing connection drops, hangs under network latency, and high resource overhead.
3. Silent File Overwrites: Naive file copies risk corrupting data during network interruptions or overwriting concurrent modifications made by remote teams.
4. Port Accessibility: Accessing remote web servers, inference APIs, or debuggers typically requires manual external SSH tunneling configuration.

@goodandready/dsh-remote-workspace solves these challenges directly within the Cordis framework. It provides an enterprise-grade remote development subsystem with persistent SSH2 connection pooling, atomic SFTP file operations, conflict-aware 3-way synchronization, dynamic port tunneling, and an interactive Web UI settings card styled after dsh-clinebot.

---

🏗️ Architecture

graph LR
  subgraph DSH["DeepSeek Harness (Cordis Architecture)"]
    UI["Web UI Client Card<br/>(dsh-clinebot style)"]
    Routes["REST API Routes<br/>(/state, /browse, /test, /sync)"]
    Tools["Model Tools<br/>(remote_exec, remote_fs, sync, tunnel)"]
    Ssh["SshService<br/>(Connection Pool & Keepalive)"]
    SFTP["RemoteFsService<br/>(Atomic SFTP Streaming)"]
    Sync["MirrorSyncService<br/>(3-Way SHA-256 Engine)"]
    Tunnel["TunnelService<br/>(Port Forwarding)"]
  end

  subgraph RemoteNode["Remote Environment (Cloud VM / GPU Node)"]
    SSHD["SSH Server (:22)"]
    FS["Remote Filesystem"]
    AppPort["Remote Dev Server / Service"]
  end

  UI -->|REST API| Routes
  Routes --> Ssh
  Routes --> SFTP
  Routes --> Sync
  Tools --> Ssh
  Tools --> SFTP
  Tools --> Sync
  Tools --> Tunnel
  Ssh -->|SSH2 Channel / Key or Password| SSHD
  SFTP -->|SFTP Subsystem| FS
  Sync -->|Pull / Push Differential| FS
  Tunnel -->|Local Port Forwarding| AppPort

  classDef default fill:#1e1e2e,stroke:#6366f1,stroke-width:1px,color:#cdd6f4;
  classDef accent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#a6e3a1;
  class DSH,RemoteNode accent;

---

✨ Full Feature Breakdown

1. SshService — High-Performance Connection Pool & Authentication

• Connection Pooling: Maintains reusable, authenticated SSH2 client sessions keyed by host:port:username.
• Dual Authentication Modes:
  • SSH Private Key: Path to local key (~/.ssh/id_ed25519), raw PEM string, and optional passphrase decryption.
  • Password Authentication: Direct secure password authentication.
• Diagnostic Health Probing: Built-in testConnection executes latency measurements (ping in milliseconds) and detects remote OS architecture (uname -srm).
• Resilience: Heartbeat keep-alive packets prevent timeout disconnects from aggressive firewalls.
• Proxy and jump hosts: proxyCommand runs an OpenSSH-style command. Tokens are %h, %p, %r, %n, and %%. jumpHosts is an ordered list of profile ids. A comma-separated jumpHostId is the fallback. The first bastion comes from the pool. Each later bastion has its own connection, released when the target session ends.
• Agent and one-time codes: agentPath selects an agent socket. An empty value uses SSH_AUTH_SOCK, or Pageant on Windows when that is the configured path. A keyboard-interactive server shows its prompt on the card. The prompt expires after 60 seconds.
• Idle pool: a pooled connection with no tunnel and no running command closes after 30 minutes. The next command opens it again.
• Reconnect before output: if the connection drops before the command prints anything, the command runs again, up to three times. A command timeout, output that already started, or idempotent: false is not repeated.
• Separate terminal session: the terminal does not share the pooled connection. Closing the terminal closes only that SSH session.

2. RemoteFsService — Resilient SFTP Operations

• Atomic File Writing: Writes content to an ephemeral temporary file (.tmp.<timestamp>.<hash>) and renames it atomically upon complete upload, preventing partial or corrupted files.
• Streaming Reads: High-speed chunked stream reader supporting large files with selectable encoding.
• Filesystem Primitives: Provides stat, listDir, recursive mkdir (like mkdir -p), and recursive remove directly over the SFTP subsystem.

3. MirrorSyncService — Conflict-Aware 3-Way Synchronization

• State Manifest Tracking: Maintains baseline SHA-256 hash digests in .dsh-sync-manifest.json for all tracked files.
• Conflict Prevention: Detects when both local and remote files have diverged since the last synchronization baseline, halting operations with a detailed conflict report rather than silently overwriting changes.
• Selective Sync: Supports directional pull (remote → local) and push (local → remote) with optional force override.
• Dry-Run Inspection: Allows agents or developers to preview affected files, additions, modifications, and deletions before applying changes.
• Smart Exclusion: Built-in default ignore patterns for version control, dependencies, and temporary files (.git, node_modules, .dsh, .worktrees, .DS_Store).

4. TunnelService — Integrated SSH Port Forwarding

• Local Port Forwarding: Binds a local port on the DSH host and securely forwards all incoming TCP traffic over the encrypted SSH channel to any target port on the remote host (e.g. 127.0.0.1:8080 → remote 127.0.0.1:8080).
• Dynamic Lifecycle: Start, stop, and enumerate active tunnels programmatically or via UI.

5. tools.js — Ergonomic Agent Tools

Four orthogonal, high-leverage tools exposed directly to LLM agents:

• remote_exec: Execute shell commands on the remote workspace with custom working directory and exit code capture.
• remote_fs: Read, write, inspect, list, create directories, or delete files on the remote filesystem.
• remote_sync: Synchronize files between the local mirror and remote server with conflict awareness and dry-run mode.
• remote_tunnel: Start, stop, or list SSH port-forwarding tunnels.
• remote_hosts: Return a compact markdown table of configured hosts. Secrets, private keys, and proxy commands are omitted. query is required; an empty query lists every host.
• remote_cluster: Run one command on every host that matches an environment, every requested tag, and an optional alias list. maxWorkers defaults to 8.

6. client.js — Native DSH Settings Card UI

• Designed strictly to DSH UX guidelines and styled after dsh-clinebot.
• Segmented Auth Switcher: Clean tabbed toggle between Private Key and Password authentication.
• Remote Directory Browser Modal: Interactive remote file browser with breadcrumb navigation and one-click path selection.
• Connection Diagnostic Badge: Real-time ping testing with visual latency indicators and remote OS display. The header badge follows /dsh-remote-workspace/state: it shows a loading, empty, ready, or unavailable connection instead of a permanent Ready label.
• Action Triggers: Quick buttons for directional synchronization and tunnel monitoring. A failed save, delete, activation, directory browse, or tunnel stop shows the server error in an alert on the card. Test Connection posts the profile fields, including host.
• Plugin list label: English Remote Workspace or Chinese 远程开发工作区, taken from the dictionaries already loaded with the card.
• Updater version: the row shows the installed version returned by the status request. Before that response it shows "Version unknown".
• Host groups: profiles can carry environment, tags, location, and description. The card can list them flat, by environment, or by tag, and test one group together.
• Files: the Files tab uploads and downloads a remote file. Progress follows the bytes already moved, and Cancel stops the transfer. Files larger than 512MB are refused.
• Terminal font: terminalFontFamily is a CSS font family for the terminal. Leave it empty for the default monospace stack.
• Hidden tab: status polling pauses while the browser tab is hidden and refreshes when the tab returns.
• Sidebar workspace: a Remote button in the left navigation opens the center column with Hosts, Terminal, Files, Containers, Tunnels, and Cluster. Switching back to chat hides that column and keeps the open terminal.

---

📦 Installation

Install into your DSH web profile:

dsh plugin --profile web add @goodandready/dsh-remote-workspace

Or install using the DSH CLI:

dsh plugin add @goodandready/dsh-remote-workspace

---

⚙️ Configuration Reference

Configuration can be managed either via the Web UI Settings card or defined in your DSH configuration files (settings.yaml / Cordis config):

dsh-remote-workspace:
  activeProfileId: "prod-cloud-gpu"
  profiles:
    - id: "prod-cloud-gpu"
      name: "Cloud GPU VM"
      host: "remote.example.com"
      port: 22
      username: "deploy"
      authType: "key"              # "key" or "password"
      privateKeyPath: "/home/user/.ssh/id_ed25519"
      passphrase: ""
      password: ""
      remoteWorkspace: "/var/www/my-project"
      localMirrorPath: "/home/user/projects/my-project"

Parameters Table

Parameter	Type	Default	Description
profiles	Array<Profile>	[]	List of configured remote server profiles.
activeProfileId	string	""	ID of the currently active remote host profile.
profile.id	string	""	Unique identifier for the profile.
profile.name	string	""	Human-readable label displayed in UI.
profile.host	string	""	Hostname, FQDN, or IP address of the remote host.
profile.port	number	22	Remote SSH port.
profile.username	string	""	SSH login username.
profile.authType	string	"key"	Authentication method: "key" or "password".
profile.privateKeyPath	string	""	Path to local OpenSSH private key file.
profile.privateKey	string	""	Raw PEM/OpenSSH private key content (alternative to path).
profile.passphrase	string	""	Passphrase for encrypted private keys.
profile.password	string	""	Password for password-based authentication.
profile.remoteWorkspace	string	""	Base directory of the project on the remote machine.
profile.localMirrorPath	string	""	Local directory for mirror synchronization.
profile.agentPath	string	""	SSH agent socket. Empty uses SSH_AUTH_SOCK.
profile.proxyCommand	string	""	OpenSSH ProxyCommand. Tokens: %h %p %r %n.
profile.jumpHosts	string[]	[]	Bastion profile ids, first hop first.
profile.jumpHostId	string	""	Comma-separated bastion ids when jumpHosts is empty.
profile.environment	string	""	Group and cluster filter, compared case-insensitively.
profile.tags	string[]	[]	Labels. A cluster filter requires every tag.
profile.location	string	""	Free-form place label.
profile.description	string	""	Free-form note.
terminalFontFamily	string	""	Terminal CSS font family. Empty keeps the default monospace stack.

---

🔌 Model Tools Reference

remote_exec

Executes a bash or shell command on the active remote host.

• Parameters:
  • command (string, required): Shell command line to execute.
  • cwd (string, optional): Working directory on remote host. Defaults to remoteWorkspace.
• Returns: { exitCode: number, stdout: string, stderr: string }

remote_fs

Performs filesystem operations over SFTP.

• Parameters:
  • action (string, required): One of "read", "write", "stat", "list", "mkdir", "remove".
  • path (string, required): Target remote path (absolute or relative to workspace).
  • content (string, optional): Required for "write" action.
  • recursive (boolean, optional): Recursive flag for "remove" action.
• Returns: Result object depending on action ({ content }, { stat }, { entries }, { ok: true }).

remote_sync

Runs 3-way conflict-aware synchronization between local and remote directories.

• Parameters:
  • direction (string, required): "pull" (remote → local) or "push" (local → remote).
  • force (boolean, optional): Overwrite conflicts if true.
  • dryRun (boolean, optional): Simulate changes without writing to disk.
• Returns: Sync summary object with applied actions, changed files, and any detected conflicts.

remote_tunnel

Manages SSH local port forwarding tunnels.

• Parameters:
  • action (string, required): "start", "stop", or "list".
  • localPort (number, optional): Local port to bind (for "start").
  • remotePort (number, optional): Remote destination port (for "start").
  • tunnelId (string, optional): Identifier of the tunnel to terminate (for "stop").
• Returns: { tunnelId, localPort, remotePort } or { tunnels: [...] } or { success: boolean }.

remote_hosts

Lists configured hosts for the model without secrets.

• Parameters:
  • query (string, required): Case-insensitive match against name, host, or id. An empty string lists every host.
• Returns: A markdown table. Password, private key, key path, passphrase, agent socket, and proxy command are omitted.

remote_cluster

Runs one shell command on a filtered set of hosts.

• Parameters:
  • command (string, required): Shell command.
  • environment (string, optional): Exact environment name.
  • tags (string, optional): Comma-separated tags. Every tag must match.
  • aliases (string, optional): Comma-separated profile ids or names.
  • maxWorkers (number, optional): Parallel connections. Default 8.
• Returns: One row per host with success, exit code, duration, stdout, stderr, and error.
• Limit: A host that fails to connect is reported on its own row. Other hosts still run.

---

🌐 HTTP API Routes Reference

All endpoints are hosted under /dsh-remote-workspace:

Method	Route	Description	Request Body
GET	/dsh-remote-workspace/state	Returns profiles, active profile ID, and active tunnels.	—
POST	/dsh-remote-workspace/profiles/save	Create or update a profile.	Profile JSON object
POST	/dsh-remote-workspace/profiles/delete	Delete a profile by ID.	{ id: string }
POST	/dsh-remote-workspace/profiles/active	Set active profile.	{ id: string }
POST	/dsh-remote-workspace/test	Test SSH connectivity and latency.	Profile JSON object
POST	/dsh-remote-workspace/browse	List directory contents for remote browser modal.	{ profile: object, path: string }
POST	/dsh-remote-workspace/sync	Trigger manual pull or push synchronization.	{ direction: "pull" | "push", dryRun?: boolean, force?: boolean }
POST	/dsh-remote-workspace/profiles/import-ssh-config	Import ~/.ssh/config, or the posted config text.	{ content?: string }
POST	/dsh-remote-workspace/profiles/test-group	Test the stored profiles whose ids are posted.	{ ids: string[] }
POST	/dsh-remote-workspace/cluster	Run one command on the filtered stored profiles.	{ command, environment?, tags?, aliases?, maxWorkers? }
GET	/dsh-remote-workspace/file/download	Stream a remote file. Query: profileId, filePath.	—
POST	/dsh-remote-workspace/file/upload	Upload a raw file body. Query: profileId, filePath.	file bytes
POST	/dsh-remote-workspace/terminal/font	Save the terminal font family.	{ fontFamily: string }
POST	/dsh-remote-workspace/auth/keyboard	Submit a keyboard-interactive code.	{ id, answers }

---

📄 License

MIT © GooDAnDReaDY

13. Smart Tarball Sync & Diagnostics (v0.3.1)

• 🚀 Fast Tarball Stream: High-throughput directory sync via on-the-fly streaming tar -czf bypassing per-file roundtrips.
• 🩺 Remote Diagnostics (remote_diagnose): Instant one-shot checks for occupied ports (ports), OOM killer events (oom_killer), disk consumption (disk), and service crash-logs (service_logs).
• 📥 Import from ~/.ssh/config: One-click import of hosts, keys, and ProxyJump configurations directly into the encrypted .env vault.
• 🗃️ Remote Environment Manager (remote_env): Inspect and atomically modify remote .env key-values with password masking and structural preservation.
• 📡 Background Anomaly Alerts: Proactive monitoring of disk (<10% free), memory (<5%), and restarting Docker containers via Cordis event bus (remote-workspace/alert).

14. DSH 0.2.0-rc.1 Alignment & Reliability Hardening (v0.3.11)

• ⚙️ DSH 0.2.0-rc.1 Settings Forms: Fully volatile Config schema leaves and dynamic whileServed client registration matching the DSH 0.2.0-rc.1 settings contract (#76).
• 🛠️ Environment & Diagnostics Endpoints: Fixed service method bindings for .env inspection, atomic variable updating, and host diagnostics (#77).
• ⏱️ Terminal Session Reaper: Automatic background sweeping of idle and abandoned PTY sessions to prevent remote connection exhaustion (#78).
• 🛡️ Tunnel Lifecycle Hardening: Mutual socket/stream teardown on network disconnect and accurate telemetry counter tracking (#79).
• 📦 Tar Stream Resilience: Uncaught exception protection for local tar extraction and zombie process termination (#80).
• 🔒 Shell Command Sanitization: Strict numeric validation and POSIX single-quoted escaping across Docker, diagnostics, and remote filesystem operations (#81).
• 💾 Binary Stream Sync: Raw buffer hashing in MirrorSyncService.pull preventing false conflicts and hash corruption on binary files (#82).
• 👀 Watcher Error Recovery: Automatic fs.watch error recovery (ENOSPC handling) and per-profile concurrency locking (#83).
• ⚡ Tab Visibility Polling Gate: Client-side background poll suppression when browser tab is hidden (#84).