dsh-wsl

English | 简体中文

A model-facing WSL tool plugin for DeepSeek Harness (DSH). It lets an agent run Linux commands through wsl.exe directly — no hand-written .sh scripts or pwsh wrappers.

Tools

The plugin registers three tools:

Tool	Purpose
wsl	Run a Linux command and return stdout/stderr with exit-code markers.
wsl-path	Convert between Windows and WSL paths via wslpath.
wsl-env	Summarize the WSL environment (distros, kernel, cpu, mem, disk).

wsl

Runs:

wsl.exe -d <distro> -e bash -lc "cd <workdir> && <command>"

and returns stdout/stderr with [exit code: N] / [killed by signal: ...] / [output truncated] markers.

wsl-path

Converts a path in either direction: C:\Users\me\a.txt -> /mnt/c/Users/me/a.txt or /home/me/a.txt -> \\wsl.localhost\Ubuntu-22.04\home\me\a.txt. Direction is auto-detected from the path, or forced with direction: 'win' | 'linux'.

wsl-env

No arguments. Returns the distribution list, default distro, kernel, CPU count, memory and disk usage so an agent knows what it is running on.

Install

1. Add the package to your DSH profile (profiles/<profile>/package.json):

   { "dependencies": { "dsh-wsl": "file:<path-to-this-repo>" } }
   

   or run dsh plugin add --profile <profile> file:<path-to-this-repo>.

2. Add a tool-wsl row to an agent preset's agent.cordis.yml:

   - id: tool-wsl
     name: 'dsh-wsl'
   

3. Restart DSH.

wsl parameters

Param	Required	Type	Notes
command	yes	string	Linux command to execute
description	yes	string	short UI label
workdir	no	string	WSL/Linux path, default ~
timeoutMs	no	number	timeout in milliseconds
distro	no	string	WSL distribution name, default Ubuntu-22.04
env	no	object	extra environment variables to export
allowDangerous	no	boolean	set true to run destructive commands

Notes

• Each call runs in a fresh bash -lc shell — no cwd/variables/functions persist between calls.
• The default distro is Ubuntu-22.04; override it per call with the distro argument or globally with the DSH_WSL_DISTRO environment variable. Edit DEFAULT_DISTRO in index.js to change the fallback.
• Windows paths (C:\...) in command and workdir are translated to /mnt/c/... automatically.
• Destructive commands (rm -rf, dd onto a block device, mkfs, shutdown, fork bombs, …) are refused unless the call passes allowDangerous: true.
• Uses wsl.exe -e (--exec) so quoting and $VAR expansion behave like a normal shell; the default -- pass-through mangles single quotes and variables.

Install from the plugin list

The package declares a dsh.bundle manifest (see package.json), so once the repository is listed it can be installed by name, e.g. dsh plugin add dsh-wsl, and storefronts will offer it for one-click install. Installing from a local path (file:) as shown above keeps working either way.

How it works

The plugin is a cordis module that injects the host-plane tools and subprocess registries:

• apply() registers three tools, each with a JSON-schema parameter definition, an output schema, a render hook and an async execute.
• execute() spawns wsl.exe -d <distro> -e bash -lc "<cd workdir && command>" through the host subprocess service, with stdin ignored, stdout/stderr capped at 64 KiB (spilling to disk up to 64 MiB), a 3 s grace period after abort, and an optional timeoutMs that aborts the call.
• env entries are exported at the front of the command so they reach the Linux side reliably; Windows drive paths are rewritten to /mnt/... before the command is built.
• Output is returned as { exitCode, signal, stdout, stderr, truncated }; the render hook formats it into text with [exit code: N] / [killed by signal: ...] / [output truncated] markers.
• A destructive-command guard runs on the final command string before dispatch and refuses matched patterns unless allowDangerous is set.

The plugin publishes no services of its own, so it sits loose in an agent preset without a realm.

Development

The plugin is plain ESM with no build step or runtime dependencies outside the DSH host plane. Iterate by pointing a profile dependency at the checkout:

{ "dependencies": { "dsh-wsl": "file:/path/to/dsh-wsl" } }

then restart DSH and exercise the tools from a session that uses a preset containing the tool-wsl row.

Customization points live at the top of index.js: DEFAULT_DISTRO, DEFAULT_WORKDIR, the output caps, the grace period and the destructive-pattern list.

Listing

The repository carries the dsh-plugin topic and is listed under the wsl category of the awesome-dsh-plugin community list.