dsh-remote-workspaces

English | 中文

Open folders on remote hosts over SSH as first-class DeepSeek Harness workspaces.

What it does

Once a remote directory is opened as a workspace, the agent's file tools (read / write / edit / grep / glob) and shell commands land directly on the remote host over SSH, not a local mirror. There is no mirroring and no sync: every operation is executed remotely in real time, and local workspaces keep their full sandbox behavior.

Features

• Open a remote folder as a workspace — browse the remote filesystem, pick a directory, and the harness adopts it as if it were local. All I/O routes to the remote.
• Multi-machine registry — add, edit, and remove SSH hosts (alias, host, port, user, key or password). Credentials are AES-256-GCM encrypted at rest and never sent back to the browser.
• ~/.ssh/config import — list configured aliases and pre-fill the connection form.
• Connection test — verify a host before using it.
• Transparent tool routing — read/write/edit go through SFTP, grep/glob run ripgrep on the remote, and bash/pwsh commands execute over ssh2 exec. Routing follows the session, not the path's spelling: in a remote workspace every command runs on that host, and a workdir naming no path there is refused rather than run locally. Local sessions keep the harness's sandbox.
• Policy-aware remote mutations — the harness file policy applies to remote workspaces too: read-only denies write/edit and remote shell commands, workspace-write confines write/edit to the remote workspace root (plus /tmp) while remote shell commands need a danger-full-access approval, and danger-full-access delegates to the SSH account.

How it works

The bundle has a host half and a browser half:

• Host (src/index.js) — an SSH/SFTP transport built on ssh2, an encrypted machine store, the routing filesystem (ctx.fs) and shell (ctx.shell) providers, remote-aware grep/glob tools, and a remoteWorkspaces Remote namespace exposed through Typert.
• Browser (src/client.js) — a "Remote Workspaces" settings section (hosts grouped by machine) and a workspace-add picker.

Opening a remote directory creates an anchor: a real but empty local directory adopted by the harness as the workspace identity, plus a metadata file recording its remote origin. A registry (anchors.json) maps that anchor to its remote host and path, and every file/command operation is routed to the remote by that lookup:

$DSH_HOME/remote-workspaces/
├── machines.json              # host registry (credentials encrypted at rest)
├── anchors.json               # anchor → remote origin routing registry
└── <host>-<user>-<port>/      # per-host anchors
    └── <encoded-path>/        # one empty anchor per remote path
    │   └── .dsh-remote-meta.json

The full remote path is encoded into the anchor name (path separators and Windows-illegal characters become --), so /home/test and /data/test map to distinct directories (home--test vs data--test).

Requirements

• A DeepSeek Harness installation (the plugin resolves its host services at runtime).
• Node.js ≥ 18 (the harness itself runs on Node 22+).
• ssh2 is the only transport dependency; no external ssh binary is needed.
• The remote host needs rg (ripgrep) for grep/glob, and sha256sum (or shasum) for post-write verification — both degrade gracefully when absent.

Installation

Install from this repository:

dsh plugin --profile web add github:januory/dsh-remote-workspaces

Once published to npm, install the released package directly:

dsh plugin --profile web add dsh-remote-workspaces

Install from source:

git clone https://github.com/januory/dsh-remote-workspaces.git

cd dsh-remote-workspaces

pnpm install  # install the ssh2 transport dependency

dsh plugin --profile web add .

Remove it with:

dsh plugin --profile web remove dsh-remote-workspaces

Maintainer note: the npm package name is now dsh-remote-workspaces (the early git install used remote-workspaces); older installs must first run dsh plugin --profile <name> remove remote-workspaces, then install under the new name.

Usage

1. Open Settings → Remote Workspaces.
2. Add an SSH host (or import one from ~/.ssh/config), then Test connection.
3. In the workspace-add flow, choose a remote host, browse to a directory, and open it. The harness adopts the empty anchor as a workspace, and reads, writes, searches, and shell commands all execute on the remote.

Remote API

The host exposes a remoteWorkspaces Remote namespace (Typert) with these invocations: listMachines, saveMachine, deleteMachine, listSshAliases, sshAliasDetail, testConnection, listRemoteDir, and openRemoteWorkspace.

Repository structure

src/                          # the DSH bundle source
  index.js                    # host entry (routing fs/shell, search tools, Remote namespace)
  client.js                   # browser entry (settings UI + picker)
  transport.js                # ssh2 transport (SshClient, exec, sha256)
  routing-fs.js               # routing filesystem (remote SFTP / local fence)
  fs-sftp.js                  # SFTP filesystem backend
  local-backend.js            # local filesystem backend
  containment.js              # local sandbox containment fence
  shell-exec.js               # SshShellExecutor (remote ssh2 exec / local subprocess)
  search.js                   # remote-aware grep/glob tools
  anchor.js                   # local anchor layout (empty dir + meta)
  registry.js                 # anchors.json routing registry
  machine-store.js            # host registry (encrypted at rest)
  ssh-config.js               # ~/.ssh/config parser
  ssh-uri.js                  # ssh:// URI parsing + detection
  errors.js                   # error codes
cordis.patch.yml              # DSH bundle patch (swap in the routing providers)
package.json                  # package + dsh manifest
test/                         # unit + integration tests

Testing

Pure unit tests (no host required) run anywhere:

pnpm test

The integration suite exercises a real SSH host and expects the machine registry to be configured first (it targets the first machine in the registry, or the one aliased test):

pnpm test:integration

Publishing (maintainers)

Releases are fully manual with zero input: the version comes straight from package.json — commit the new version on main first, then GitHub Actions → release → Run workflow. The workflow runs the unit tests (npm test), guards that the v<version> tag does not exist yet (prevents duplicate releases), publishes to npm with provenance (npm publish --provenance), creates and pushes the v<version> tag, and creates a GitHub Release with --generate-notes.

Prerequisites: configure an NPM_TOKEN secret in Settings → Secrets and variables → Actions (an npm automation token, or a granular token with publish permission on the package); the publishing account must be the npm user owning the package name.

Equivalent manual flow:

npm login

npm publish --provenance

git tag "v$(node -p \"require('./package.json').version\")"

git push origin --tags

License

MIT