📦 @goodandready/dsh-remote-workspace
Enterprise Remote Workspace for DeepSeek Harness: SSH, SFTP File Sync & Tunneling
🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明
⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it.
🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
|
⚡ 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:
- Local Boundary Limitation: Standard DSH operations and agent tools run exclusively against the local machine where DSH is deployed.
- 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.
- Silent File Overwrites: Naive file copies risk corrupting data during network interruptions or overwriting concurrent modifications made by remote teams.
- 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. |
|
🔌 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 |
📄 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).
