dsh-remote-explorer
远程开发启动器：把 dsh 装到远程主机并在本机浏览器中使用，凭据不离开本机
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:btsd321/dsh-remote-explorer#84964ff7c84357a9a0d7bec238d866addb26828eRemote Explorer 以 dsh-remote-explorer 发布，当前版本为 0.7.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
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.
packageManager); release packages bundle their own Node runtime.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).Host entries in ~/.ssh/config, or ad-hoc user@host[:port] (IPv6 must go through the config).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).
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
Download the archive for your platform from the release page (produced by the packaging script, 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.
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,esbuildvia tsx,ssh2) — the firstdsh plugin addfails withERR_PNPM_IGNORED_BUILDSregardless 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 pendingallowBuildsentries tofalsein~/.dsh/profiles/web/pnpm-workspace.yaml, remove the half-committeddsh-remote-explorerentry fromdependenciesin~/.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: hosts | connect <alias> [remote-dir] | status | disconnect <alias|session-id> [--keep-remote]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 stops the remote dsh too by default (keepRemoteOnDispose: true in the profile patch keeps it); LLM keys are read from the environment of the process that launched dsh. See the usage guide.
Examples below use the source-run form. With a release package, replace
pnpm exec tsx src/cli/bin.tswith./dsh-remote-explorer(Windows:dsh-remote-explorer.cmd) — the options are identical.
# List hosts from ~/.ssh/config
pnpm exec tsx src/cli/bin.ts list
# Diagnose a host's provisioning conditions (replace myhost with your alias or user@host[:port])
pnpm exec tsx src/cli/bin.ts doctor myhost
pnpm exec tsx src/cli/bin.ts doctor myhost --refresh-mirrors # force re-benchmark mirrors
# Main command: provision → start remote dsh → build tunnel → open browser (long-running)
# Export the API key for whichever provider you use (provider list comes from ~/.dsh/settings.yaml)
DEEPSEEK_API_KEY=sk-xxx pnpm exec tsx src/cli/bin.ts connect myhost --cwd //home/youruser
# Show all sessions maintained on this machine
pnpm exec tsx src/cli/bin.ts status
# Stop remote dsh
pnpm exec tsx src/cli/bin.ts kill myhost --all
# Clean up stale remote resources (old versions, dead session dirs; running sessions are protected)
pnpm exec tsx src/cli/bin.ts clean myhost
pnpm exec tsx src/cli/bin.ts clean myhost --keep 2 # keep 2 versions per category
# Provision only, don't start services (idempotent; reuses installed versions)
pnpm exec tsx src/cli/bin.ts provision myhost --cwd //home/youruser
# Use a different ssh config file
pnpm exec tsx src/cli/bin.ts list --ssh-config /path/to/config
After connect, the process must stay running — the local tunnel listener and LLM proxy live inside it. Ctrl-C stops the remote dsh as well (disconnect = clean). To disconnect but keep the remote process for reuse, add --keep-remote. If the session enters a terminal state due to failure, the remote process is also preserved.
For a detailed walkthrough of every command and option, see docs/usage-en.md.
Model calls do not go directly to the public internet. Instead, they traverse a reverse SSH tunnel. Multi-provider support: the proxy routes by path prefix — DeepSeek's native channel uses /anthropic, and other locally configured providers each use /r/<provider-name>. Routing is extracted automatically — no manual configuration needed.
Remote dsh ──(placeholder token)──▶ Remote 127.0.0.1:<reverse-port>/r/<provider> ──SSH reverse tunnel──▶ Local proxy
├─ /anthropic → api.deepseek.com
└─ /r/<provider> → corresponding upstream
(real key injected per route)
DEEPSEEK_API_KEY, etc.) exists only in the local process — never written to remote disk, never placed in the remote environment. The remote process environment contains proxy tokens (random values).process.env first, falls back to $DSH_HOME/.credentials.yaml refs — aligned with dsh's own credential resolution priority. Keys stored via the dsh Models page work automatically without exporting to environment variables.profiles/desktop/cordis.patch.yml, Web dsh reads profiles/web/cordis.patch.yml, CLI reads $DSH_HOME/settings.yaml. Configuration is mirrored into the remote session (keys like agent-default-model are mirrored so the remote default model matches local). Only provider baseURL is redirected into the tunnel. Only configuration is mirrored (credential references, no secrets); .credentials.yaml is never mirrored (it may contain real keys)..runtime/ (token at permission 600), and read back on reconnect and reuse.The remote dsh is launched by this tool, so its environment carries no proxy variables by default — on a remote host without direct internet, installing a GitHub plugin (which uses HTTPS git ls-remote) times out even though SSH (port 22) works. Setting DSH_REMOTE_PROXY on the local machine fixes that: the launcher injects http_proxy / https_proxy / ALL_PROXY (both letter cases) into the remote dsh process, pointing at the proxy port your SSH reverse tunnel exposes on the remote (e.g. http://127.0.0.1:18890):
DSH_REMOTE_PROXY=http://127.0.0.1:18890 DEEPSEEK_API_KEY=sk-xxx pnpm exec tsx src/cli/bin.ts connect myhost
dsh itself passes proxy variables through to the git/pnpm child processes it spawns, so plugin installs and dependency fetches go through the same proxy. Leaving DSH_REMOTE_PROXY unset injects nothing — machines with direct internet are unaffected. In plugin form, per-host custom variables (the gear button on the panel, persisted in ~/.dsh/remote-host-env.json) take precedence over this fallback.
Modeled after VS Code's ~/.vscode-server single-root self-contained model: everything this tool writes on the remote is inside ~/.dsh-remote-explorer/btsd321/ (installations, per-session state, npm cache, temporary files). It never writes to remote ~/.dsh (official dsh's home) or ~/.npm (shared npm cache). The remote dsh's skill directory is also redirected into the session (DSH_AGENTS_HOME), not the machine-global ~/.agents.
doctor's isolation check section reports usage.rm -rf ~/.dsh-remote-explorer/btsd321, one command, clean.dsh plugin on the remote; content-addressed and concurrency-safe.When writing remote paths in Git Bash, use double slashes (--cwd //home/xxx) or set MSYS_NO_PATHCONV=1 first. MSYS rewrites /home/xxx into something like D:/SoftWare/Git/home/xxx before the argument reaches the program, which the CLI can only detect and reject.
doctor checks connectivity, platform, basic commands, disk space, installed runtimes, Node runtime stability, and live mirror latency. It is the first tool for troubleshooting remote environment issues — most remote development failures are environmental, not code.
The multi-user model follows VS Code Remote-SSH:
kill --all and clean default to acting only on sessions started from this machine (owner fingerprint written to remote .runtime/owner at session start) plus process-less leftovers; other owners' sessions are skipped and listed, --include-others restores the old full-scope behaviorRemote plugin management, two surfaces (VS Code's "manage while connected"). The plugin store is user-level (one per remote OS account, shared by all its sessions — the counterpart of ~/.vscode-server/extensions/; session profiles attach via symlink with zero copies):
Local (Windows/Linux/macOS) Remote (Linux/macOS)
┌────────────────────────────────┐ ┌──────────────────────────────┐
│ Browser │ │ dsh (full npm install) │
│ 127.0.0.1:<local-port> │ │ webserver 127.0.0.1:<port> │
└───────────────┬────────────────┘ │ │
│ HTTP / WS + session token │ ├ session / agent │
┌───────────────▼────────────────┐ forward │ ├ fs / subprocess │
│ dsh-remote-explorer CLI (long-running) │══════════════▶│ ├ terminal / lsp │
│ ├ transport ssh2 conn & fwd │ │ └ sandbox │
│ ├ provision install Node & dsh│ │ │
│ ├ tunnel port forwarding │ reverse │ │
│ ├ session heartbeat & recon │◀═════════════│ baseURL → 127.0.0.1:<rev> │
│ └ credential LLM proxy │ │ │
│ ▲ DEEPSEEK_API_KEY only here │ └──────────────────────────────┘
└───┼────────────────────────────┘
│
Real LLM API (local direct egress)
Dependencies are strictly one-directional, top to bottom; lower layers must not import upper layers:
Entry cli/
Orchestration session/
Capability provision/ tunnel/ credential/
Transport transport/
Foundation hosts/ util/
| Module | Responsibility |
|---|---|
| src/util/ | Shell escaping, error types, interactive password prompt (no echo) |
| src/hosts/ssh-config-parser.ts | Sole source of host config: parses ssh config (plus ad-hoc user@host[:port]), recursively resolves ProxyJump, applies auth overrides |
| src/transport/types.ts | Transport abstraction (designed for multiple transports; Docker/WSL possible later) |
| src/transport/ssh-transport.ts | ssh2 implementation: jump host chains, command execution, SFTP, forward/reverse forwarding, password auth (retries on rejection, up to 3) |
| src/transport/channel-pool.ts | SSH channel quota, avoids exceeding MaxSessions |
| src/transport/platform.ts | Shared platform detection and command building: arch mapping, uname parsing, PATH assembly |
| src/provision/probe.ts | Remote probe + Node stability self-check |
| src/provision/mirror-selector.ts | Live mirror latency measurement and adaptive selection |
| src/provision/remote-paths.ts |
# Type check
pnpm run typecheck
⚠️ Contributors: install the git hook once after cloning — do not commit without it.
pnpm run setup:hooks
pnpm installno longer builds anything: thepreparescript was deliberately removed, because pnpm 11 refuses to install git-hosted packages that declare any lifecycle script (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED). The plugin artifacts (lib/) are committed to the repository, and the pre-commit hook rebuilds them automatically wheneversrc/,scripts/, ortests/change. If you skipsetup:hooksand also forget to runpnpm run build:pluginmanually, your commit ships a stalelib/— everyone installing from GitHub then silently gets outdated plugin code. Without the hook, always runpnpm run build:pluginand include the updatedlib/in the same commit.
Code style guide is in docs/type_script_style.md — read it before writing any code.
Produces release packages (see Installation and running): esbuild bundles the CLI with all runtime dependencies into a single dsh-remote-explorer.cjs, then the official Node binary for the target platform is added, along with launchers and docs, and everything is archived. Output lands in dist/ (gitignored) — this does not change how the source itself runs via tsx.
pnpm exec tsx scripts/package.ts # package for the current platform
pnpm exec tsx scripts/package.ts --all # full five-platform matrix
pnpm exec tsx scripts/package.ts --os linux --arch arm64
| Option | Description |
|---|---|
--os <os> | Target OS: win32 / linux / darwin (default: current platform) |
--arch <arch> | Target architecture: x64 / arm64 (default: current architecture) |
--all | Build the full five-platform matrix; ignores --os / --arch |
--node-version <ver> | Node version to bundle (default: v24.21.0) |
--mirror <mirror> | Node download source: npmmirror (default) / official / custom URL prefix |
--out-dir <dir> | Output directory (default: dist) |
--minify | Minify the bundle (off by default, keeps readable stack traces) |
Node distributions are verified against SHASUMS256 on download and cached in dist/.node-cache, so repeated packaging skips the download. Each run prints the path, size, and sha256 of every artifact.
Apache License 2.0 — see LICENSE.
| Single source of truth for remote path rules |
| src/provision/node-installer.ts | Install Node, version-isolated, self-checks after install |
| src/provision/dsh-installer.ts | Install dsh, explicit version (no dist-tag reliance) |
| src/provision/profile-writer.ts | Per-session independent DSH_HOME and profile/patch generation |
| src/provision/provisioner.ts | Provisioning orchestration, each step idempotent |
| src/provision/remote-context.ts | Remote execution context: binds transport instance and path info |
| src/util/session-id.ts | Deterministic session id from host alias + remote directory |
| src/tunnel/port-allocator.ts | Remote port allocation and listen confirmation |
| src/tunnel/forward-local.ts | Forward tunneling, listener survives reconnection |
| src/session/remote-process.ts | Remote dsh detach launch, token capture, safe shutdown |
| src/session/lifecycle-state.ts | Session state machine, pure functions |
| src/session/heartbeat.ts | Heartbeat: process + port + HTTP application-level, single command |
| src/session/reconnect.ts | Bounded exponential backoff |
| src/session/session-registry.ts | Local session table, lock file + atomic replacement |
| src/session/session-manager.ts | Session orchestration: 5-phase open, heartbeat, reconnect, close |
| src/credential/tunnel-proxy.ts | Reverse tunnel LLM proxy (multi-provider routing), injects real keys |
| src/credential/provider-routes.ts | Extract provider routes from local config (settings.yaml / profile patch), produce remote mirror |
| src/credential/local-credentials.ts | Read local .credentials.yaml refs as env-var credential fallback |
| src/credential/token.ts | Proxy token: generation and constant-time comparison |
| src/credential/proxy-secret.ts | Credential material I/O: session-scoped token and reverse port persisted on remote |
| src/plugin/remote-plugin-store.ts | Remote plugin package management: list / install / remove / toggle |
| src/cli/ | Command dispatch, argument parsing, terminal output, per-command auth wiring |