kaixinyujue/dsh-shell-wsl

Install

The model keeps using the official `bash` tool (no new tools, no tool-layer changes); commands genuinely run in a container on the WSL2 Linux kernel. The executor declares the official `sandboxMode` capability bit (`workspace-write`), so permission presets (read-only / workspace-write / danger-full-access) integrate automatically — read-only sessions mount the workspace `:ro`, everything else mounts read-write.

See the design document: `dsh-shell-wsl-design.md` (checked line-by-line against the `@deepseek-ai/dsh` 0.1.0-rc.6 source contracts).

## Why a container, instead of the other approaches

On Windows, dsh exposes only `pwsh` by default (the official `tool-bash` is disabled on win32). The common community approaches to getting bash back each come with trade-offs:

| | **dsh-shell-wsl (this plugin)** | Git Bash (MSYS2) approaches | WSL distro-direct approaches |
|---|---|---|---|
| Runtime | **Real Linux**: WSL2 kernel + Ubuntu 24.04 userspace | MSYS2 emulation layer, not Linux | Real Linux, but tied to a specific installed distro |
| Isolation | Disposable container, destroyed via `--rm` after every call | No container isolation; runs as a host process | Distro lives forever; state accumulates across sessions |
| Permission-preset linkage | Native: read-only automatically mounts `:ro` | Most implementations require danger-full-access, or fail to start inside the sandbox | Common implementations let bash bypass the DSH file policy |
| Prerequisite | Docker Desktop only | Git for Windows | WSL2 + at least one distro |
| State & reproducibility | Stateless; every call starts from a pinned image | Stateless | Stateful; easy to pollute with earlier commands |

**The trade-off**: one container cold start per command buys you real Linux, isolation, and permission linkage. If you want a zero-dependency, millisecond-start POSIX-ish environment, a Git Bash approach fits better. If you want a stateful Linux environment deeply tied to your distro, a WSL-direct approach fits better. If you want a **clean, reproducible, permission-constrained real-Linux execution environment inside a Windows session**, this plugin is exactly that.

- **Real Linux**: genuine WSL2 kernel and Ubuntu userspace — Linux binaries, apt, pipes and process semantics work as-is
- **Zero pollution**: every command runs in a brand-new container that is destroyed afterwards; no leftover `cd`, variables, or apt installs
- **Permission linkage**: session permission presets map directly to read-only/read-write mounts (danger-full-access is equivalent to workspace-write under a container executor — see §7)
- **Complete lifecycle**: background jobs, timeout tree-kill, orphan-container cleanup, and infrastructure-error classification, all inherited from the official executor contract
- **Zero tool-layer changes**: the model keeps using the official `bash` tool; nothing new to learn

---

## 1. Environment requirements (P0 — verify before installing)

1. **Docker Desktop running** (WSL2 backend), with the `docker` CLI available on Windows:
   ```powershell
   docker version            # both client and server sections must print
   docker context show       # desktop-linux
   ```
2. **Pre-warm the image** (a first-time pull can exceed the default 120s timeout — pull it first):
   ```powershell
   docker pull ubuntu:24.04
   ```
3. **Verify the mount path** (replace the path with your workspace):
   ```powershell
   docker run --rm -v E:\your\workspace:/workspace -w /workspace ubuntu:24.04 bash -c "uname -a && pwd && ls"
   ```
   Expected: `Linux ... microsoft-standard-WSL2`, `/workspace`, and `ls` showing your Windows-side files.
4. A distro is only required for the `wsl` transport (the default docker-cli transport needs none):
   in that case also run `wsl --install -d Ubuntu` and enable WSL integration for that distro in Docker Desktop.

> Note: run the commands above in **your own terminal**. An agent's tool sandbox may block
> `docker`/WSL probing (E_ACCESSDENIED / named pipes); the plugin itself runs in the host
> process and is not affected.

## 2. Installation

Add kaixinyujue/dsh-shell-wsl to your DSH config (web profile) to enable.