dsh-remote-explorer

dsh plugin --profile web add dsh-remote-explorer

dsh-remote-explorer

[English](README.md) | [中文](README.cn.md)

Remote development launcher: install dsh on a remote host and use it from your local browser. LLM credentials never leave your machine.

Inspired by VS Code Remote-SSH, Zed, and JetBrains Gateway — code and sessions live on the remote, the local machine only renders the UI.

Supported environments

• Local (client): Windows / Linux / macOS. Node.js v20.19+ or v22+ and pnpm 11+ are only needed for the source-run mode (pnpm is the default dev package manager, pinned via packageManager); release packages bundle their own Node runtime.
• Remote host: Linux or macOS (POSIX); aarch64 (arm64) and x86_64 both work. No Node preinstalled required — the tool installs and self-checks it.
• WSL (Windows Subsystem for Linux): On Windows, WSL2 distributions are supported as remote targets. dsh is auto-installed inside WSL, tunneled via localhost forwarding — no SSH setup needed. Click the "WSL Sessions" card in the panel to use; the entry is hidden on non-Windows platforms. The reverse channel — shared by the remote-window handoff and the LLM credential proxy — supports both WSL2 networking modes (NAT binds the default-route gateway address alongside the loopback; mirrored rides the shared loopback), with automatic networking-mode detection and a reverse-link self-check after attach.
• SSH authentication: private key (IdentityFile, recommended); with no key configured, an interactive terminal prompts for a password (no echo); --password also works (leaks via process list / shell history — the CLI warns).
• Hosts come from Host entries in ~/.ssh/config, or ad-hoc user@host[:port] (IPv6 must go through the config).

Installation and running

The CLI has two run modes (identical commands and options); if you already run dsh locally, you can also install this tool as a dsh plugin (Option 3).

Option 1: run from source

The repository has no build step; .ts source is executed directly via tsx. The dev environment defaults to pnpm (version pinned via packageManager in package.json). After fetching the source:

pnpm install
pnpm exec tsx src/cli/bin.ts list

Option 2: run a release package

Download the archive for your platform from the release page (produced by the [packaging script](#packaging), named dsh-remote-explorer-<version>-<platform>.<zip|tar.gz>), unpack it, and run directly — no Node, npm, or network required on the target:

Platform · Archive · How to run after unpacking

win32-x64 · .zip · dsh-remote-explorer.cmd <command>

linux-x64 / linux-arm64 · .tar.gz · ./dsh-remote-explorer <command>

darwin-x64 / darwin-arm64 · .tar.gz · ./dsh-remote-explorer <command>

Each package bundles the official Node binary (SHASUMS256-verified at download time) and a single-file CLI dsh-remote-explorer.cjs (all dependencies bundled in). Verify the archive against the sha256 published with the release.

Option 3: install as a dsh plugin

If you already run dsh (Web/Desktop) on this machine, install this tool into dsh and manage remote sessions from a settings panel, a slash command, and agent tools:

# Requires pnpm on PATH (the dsh plugin command forwards to pnpm verbatim)
dsh plugin --profile web add dsh-remote-explorer
# When dsh is not on PATH:
npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote-explorer
# From a GitHub source (pre-built artifacts are committed; no extra config needed):
dsh plugin --profile web add github:btsd321/dsh-remote-explorer
# From a local checkout (build the plugin artifacts first):
pnpm run build:plugin && dsh plugin --profile web add /path/to/repo

Note for pnpm 11.7+ users (build-script approval gate): pnpm 11.7 treats undecided dependency build scripts as a hard failure, and this package's dependency tree carries three (cpu-features, esbuild via tsx, ssh2) — the first dsh plugin add fails with ERR_PNPM_IGNORED_BUILDS regardless of the install source. None of them are needed at plugin runtime: the artifacts are pre-built (lib/, committed) and ssh2 falls back to pure JS. Recommended: install through the dsh web GUI's plugin manager page — it offers a built-in approve-and-retry flow. CLI alternative: after the failed add, set the three pending allowBuilds entries to false in ~/.dsh/profiles/web/pnpm-workspace.yaml, remove the half-committed dsh-remote-explorer entry from dependencies in ~/.dsh/profiles/web/package.json (the failed add leaves it there, and a plain retry exits 0 without activating the plugin — a dsh CLI quirk present in 0.1.7-rc.1/rc.2), then re-run the add command.

Restart dsh web after installing. The plugin provides three surfaces:

• "Remote SSH Sessions" global panel in the left navigation: pick a host, connect in two window modes (enter current tab / open new tab), disconnect, live progress log; the advanced-options area carries three config dialogs (jump hosts — read-only for ssh-config aliases, editable for user@host direct hosts; environment variables; proxy), all remembered as your last global input and echoed in the per-connection log; the remote window carries a status pill for returning to the manager or closing/stopping the connection
• Slash command /remote-explorer: hosts | connect <alias> [remote-dir] | status | disconnect <alias|session-id> [--keep-remote]
• Agent tools remote_hosts_list / remote_connect / remote_status / remote_kill (behind dsh's regular tool-approval gate)

The plugin shares the CLI's session orchestration and remote layout (~/.dsh-remote-explorer/btsd321/), and the session table is shared in both directions: dsh-remote-explorer status shows plugin-kept sessions, and the panel shows CLI-kept ones (read-only, marked "external"). Two differences: session lifetime rides the host dsh process — quitting dsh s

…(truncated)