This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

dsh-remote

— source: plugin_wiki.wiki_content

Install & verify

dsh plugin --profile web add dsh-remote

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

• ~/.ssh/config import — the Settings page lists your Host aliases; one click fills the form (path reference only, the plugin never reads key material).
• Two-tab workspace picker (fills the native "Add workspace" flow):
• Async long tasks — rw_sync/rw_push with async: true return a taskId; progress/result/cancel via /dsh-remote/task (single-flight queue).
• The active user@host:/path is injected into every system prompt (plus active forwards).
• No official dsh-workspace core is modified — everything is delivered as a normal plugin (directory-flow holes filled by the client half at priority -100).

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

What do I need to do after installation to use it?

For first-time use, you need to add at least one SSH host (host/port/user + password or private key) in 'Settings → Remote Workspace', save it and switch to the current machine, then go to 'Add workspace', select the 'Remote' tab, choose a machine and specify the remote directory to start using it.

Does the remote machine have to be Linux?

Not required. All file operations go through the SFTP protocol layer and don't depend on remote shell, so Linux, macOS and Windows remote hosts can all list directories, read, write, modify, search and sync.

Where are passwords and host credentials stored? Is it secure?

They exist by default in the local $DSH_HOME/remote-workspaces/machines.json and .secrets/; optionally 'encrypt saved passwords' makes single machine passwords go through the system keychain (macOS Keychain / Windows DPAPI / Linux secret-tool), any failure will automatically fall back to plaintext but won't block connection.

Can host fingerprints be replaced by man-in-the-middle attacks?

TOFU (Trust on First Use) verification is enabled by default. The fingerprint is recorded on first connection, and subsequent key changes are immediately rejected; you can change it to 'verify' (reject unknown hosts) or 'off' (disable, not recommended); if you misjudge a fingerprint, use '/remote-forget-key' to reset it.

Will remote file changes be overwritten by the local workspace?

No. Both rw_sync and rw_push use three-way comparison (remote vs local vs last sync snapshot), changes on both ends are marked as conflicts and never overwritten; to overwrite remote with local, explicitly pass force=true.

What to do when error says 'Channel open failure: open failed'?

Usually caused by SSH idle timeout on the server side. Plugin 0.7.3+ will automatically discard old connections and reconnect once; if it persists, increase commandTimeoutMs / connectTimeoutMs, or actively call rw_disconnect to reconnect.

Will the built-in sidebar conflict with existing dsh-better-sidebar?

No. Since 0.7.2, dsh-better-sidebar is a hard dependency and automatically mounted; the bundle uses a dedicated dsh-remote-sidebar line ID + guard to detect if a line with the same name already exists, if so it backs off, won't register /sidebar/api repeatedly nor cause plugin startup failure.

I installed before 0.6, will old data be lost?

No. On first launch it automatically migrates ~/.dsh/remote-workspaces to $DSH_HOME/remote-workspaces; when you explicitly point to a different DSH_HOME (e.g., multiple installation instances), it skips migration to avoid accidentally moving others' data.

What happens if profile doesn't use pnpm hoisted?

Loader resolves plugin packages from profile root; if pnpm-workspace.yaml loses nodeLinker: hoisted, the embedded sidebar will report Cannot find package 'dsh-better-sidebar', just add the config back and run pnpm install once.

How do I transfer data to and from the remote machine?

Large directories use rw_sync (pull) / rw_push (push), both support dryRun preview, async background tasks, force overwrite; single files use rw_download / rw_upload (streaming fastGet/fastPut); single file changes can also directly use rw_write_file / rw_edit (with mtime optimistic lock) to bypass mirroring.

— source: plugin_wiki.faq_json

Compatibility

• DSH: ^0.1.0-rc.6
• Node: 未声明

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule