@lengmoxxl/dsh-remote-workspace

Readme

# 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 | [中文](README.zh.md)

![A session running tools inside a remote worktree](docs/screenshots/en/08-session.png)

| Machines | Connected | A worktree |
| --- | --- | --- |
| ![The machine list](docs/screenshots/en/01-section.png) | ![A connected machine and its repository](docs/screenshots/en/03-connected.png) | ![A created worktree](docs/screenshots/en/06-worktree-created.png) |

## 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

```sh
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.

```yaml
- 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