dsh-remote-workspace
A DSH plugin for working on another machine. It manages that machine's repositories and worktrees, routes the
harness's file, shell, and terminal tools to the directory you opened, and adds terminal tabs to the right Sidebar.
The model sees ordinary local paths.
English | 中文
A session running tools inside a remote worktree
Requirements
- Node 22.19+ or 24+, with
ssh configured as usual.
- DSH
0.1.6-alpha.2. Other releases are untested.
- A registered machine needs no runtime of its own, and is served on Linux or macOS on x86_64: the agent, and the
embedded-V8 PTC program host that machine's
run_code runs on, both come from this repository's Releases.
Install
dsh plugin --profile web add @lengmoxxl/dsh-remote-workspace
The plugin takes over services the base profile provides, and the host plane holds one implementation per service. Add
these four lines to $DSH_HOME/profiles/web/cordis.patch.yml. Without them the plugin still loads, does not route, and
says so on stderr.
- id: subprocess
disabled: true
- id: fs-sandbox
disabled: true
- id: bash-sandbox
disabled: true
- id: pwsh-sandbox
disabled: true
Then start the profile with dsh --profile web. The package ships the built lib/, so nothing is compiled on this
machine. To work on the plugin itself, clone the repository, run npm install && npm run build, and add the checkout
path instead.
Permissions and risks
This plugin is high-privilege by design: it runs commands, opens terminals, and reads and writes files on every machine
you register, as the SSH account it reaches. Anyone holding a machine's token and a way to its loopback port can act as
that account.
- The host half routes
ctx.fs, ctx.subprocess, ctx.shell, and ctx.tty. The four stock providers are disabled
in cordis.patch.yml above, so the paths this plugin routes answer through it instead of them.
- The agent binary is downloaded from this repository's GitHub Releases, checked against
SHA256SUMS, uploaded to
~/.dsh/remote-agent/ on the machine, and started there. It listens on 127.0.0.1 only, reached through ssh -L;
its token file and this host's node registry are both mode 600.
node-pty is a native dependency with a prebuilt binding: Sidebar terminals on this host run through it.- The PTC program host is a second binary from the same Release — a V8 engine, so far larger than the agent. It is
fetched and uploaded in the background once a machine connects, so the first program run there does not wait on it.
- Outbound network access is the GitHub Releases download and the
ssh connections you configure. Nothing else leaves
the machine.
What it does
- Adds machines over SSH, and a built-in
Local machine for this host. The agent is downloaded from this repository's
Releases, checked against SHA256SUMS, and reached over ssh -L, so nothing has to be installed on the machines.
- Registers any directory as a repository. Git is not required, and a plain directory can become a repository later.
- Cuts worktrees from a repository, adopts worktrees that already exist, or opens the repository directory itself.
Removing a worktree can delete its branch as well.
- Opens a directory as a workspace; the file, shell, and terminal tools then run on the machine that owns it.
- Opens terminal tabs in the right Sidebar, one per Session. The Terminal entry first lists that Session's live
shells — including one a page reload or a closed tab detached — so one can be reattached or ended.
- Lets the agent work in a terminal that has a tab open. It lists them, reads output, writes text and keys (including
ctrl+c), and waits for output to appear. It does not create or close terminals.
- Runs PTC programs —
run_code — in the world their workspace belongs to. A program aimed at a routed workspace runs
on that machine, on the embedded-V8 program host this plugin installs beside the agent, which is why the machine needs
no Node. Only the declared bindings cross the wire: on a remote machine the program reaches the filesystem and shell
through the tools it calls, not through ambient Node APIs.
Usage
Settings → Remote workspaces. Add a machine with an SSH destination and a token — any string; it is the daemon's
shared secret. Local needs neither. Machines connect on their own, and one that stays unreachable shows a Connect
button. Register a repository, then use a row's menu to open, close, or remove what it holds.
Terminal. The right Sidebar's add control has a Terminal button: it lists the Session's live terminals and
offers a new one. Manage terminals in the panel's status bar opens a second terminal tab beside the one in view, where
the chooser offers a fresh shell or one that is already running; a shell another tab already shows is marked
Already open, and picking it brings that tab forward. Closing a tab leaves that shell running — it shows up in the
chooser as detached — and a row's close control in the chooser, which the panel's Manage terminals control opens, is what ends it.
Hiding the tab, switching Session, or collapsing the sidebar also leaves a shell running.
Terminal appearance. Font, size, line height, scrollback, and cursor blink live in the shell's own settings:
Plugins → remote-workspace. They are stored in the settings document, so every
page of this deployment draws a terminal the same way.
Config
| Field | Default | Meaning |
|---|
worktreeRoot | ~/.dsh/worktrees | Root every managed checkout is cut under, on every machine. |
shell | unset | Program the Sidebar terminal runs; unset uses the machine's own login shell. |
shellArgs | ['-l'] | Arguments after shell; ignored while shell is unset. |
graceMs | 3000 | How long a closing terminal is given to exit, in milliseconds. |
detachGraceMs | 0 | Safety valve: how long a terminal whose socket went away (a reload, a dropped connection) is kept for a reattach, in milliseconds. 0 — the default — keeps it for as long as its process lives. |
MIT
