Introduction

When developing DSH agents on Windows, many tasks require calling the shell: executing scripts, checking files, installing tools, and processing logs. If the current environment only supports PowerShell and the commands depend on bash syntax or Linux distributions, the execution layer will be limited.

@zimzaza4/dsh-bash-win is a Cordis plugin that provides git_bash and wsl_bash tools for DeepSeek Harness (DSH) on Windows. It integrates with local Git Bash and WSL2, and offers approval, sandboxing, background tasks, foreground timeouts, and web terminal cards.

Plugin Positioning

Maintained by zimzaza4, the npm package name is @zimzaza4/dsh-bash-win, the repository path is zimzaza4/dsh-bash-win, and it is licensed under MIT.

It solves the problem of calling bash in the DSH environment on Windows, providing control over execution permissions, approval, sandboxing, and task lifecycle.

Core Capabilities

git_bash

The git_bash backend is based on local Git Bash (MSYS2).

Supports:

  • Approval mode: require_approval: true
  • Sandboxing: sandbox: true attempts windows-acl sandboxing; in restricted mode, it truthfully reports runner failures
  • Background tasks: run_in_background: true, with job_output / job_kill
  • Foreground execution: timeoutMs terminates the entire process tree on timeout and supports call cancellation

wsl_bash

The wsl_bash backend is based on WSL2 (Linux).

Supports:

  • WSL bwrap sandbox: sandbox: true
  • Privilege escalation approval: involving sandbox_permissions and justification
  • Background tasks: run_in_background: true, with job_output / job_kill
  • Foreground execution: timeoutMs terminates the entire process tree on timeout and supports call cancellation
  • Sandbox mode requires the distribution to have bubblewrap installed

Common Capabilities

Both tools support:

  • Auto-detection of Git Bash and WSL paths, overridable via plugin config or environment variables
  • Output collection memory limit of 256 KiB, with truncation and spill file creation when exceeded
  • Web terminal card: terminal icon, expandable output, exit code status

Installation and Enabling

The plugin can be installed into a DSH profile. Here, we use the web profile corresponding to dsh web.

Execute the installation command:

dsh plugin --profile web add @zimzaza4/dsh-bash-win

After installation, a restart of dsh web is required for it to take effect. After restarting, git_bash and wsl_bash should appear in new sessions.

Execute the uninstallation command:

dsh plugin --profile web remove @zimzaza4/dsh-bash-win

A restart of dsh web is also required after uninstallation.

Configuration

Path resolution priority: plugin config > environment variables > auto-detection.

You can configure Git Bash, WSL executable, and default distribution in cordis.patch.yml:

# cordis.patch.yml
- insert:
    - id: tool-bashx
      name: '@zimzaza4/dsh-bash-win'
      config:
        bashPath: 'D:\tools\Git\bin\bash.exe'   # Custom Git Bash
        wslPath: 'C:\Windows\System32\wsl.exe'  # Custom WSL
        wslDistro: 'Debian'                     # Default distribution

Alternatively, you can use environment variables:

DSH_BASHX_BASH_PATH
DSH_BASHX_WSL_PATH
DSH_BASHX_WSL_DISTRO

Permissions and Security

By default, execution has no sandbox and full permissions. Both git_bash and wsl_bash run directly by default and can read/write any path. The plugin runs with the current DSH process permissions. Before installation, you should review the source code and license, and ensure the process permissions meet your expectations.

Approval only appears in two scenarios:

  1. Explicit approval mode: require_approval: true
  2. Privilege escalation request after boundary crossing: involving sandbox_permissions and justification

Execution paths themselves do not trigger approval. Sandboxing handles boundary crossing by rejecting the action, rather than popping up a dialog.

When wsl_bash has sandbox: true set, it wraps commands with bwrap inside WSL. git_bash does not have file sandboxing; when sandbox: true is set, it attempts windows-acl sandboxing and truthfully reports runner failures in restricted mode.

The privilege escalation ladder ranges from workspace-write to danger-full-access, following the official approveEscalation process, which requires user approval.

Applicable Scenarios and Precautions

Suitable for the following scenarios:

  • Need to call Git Bash / MSYS2 commands
  • Need to call WSL2 / Linux commands
  • Need to add approval, sandboxing, background tasks, and terminal cards to bash tools

Runtime dependencies:

  • Git for Windows as needed
  • WSL and distribution as needed
  • When using wsl_bash sandbox, the distribution must have bubblewrap installed
  • Peer dependencies @deepseek-ai/dsh-tools and @deepseek-ai/dsh-sandbox, provided by the host

Precautions:

  • After changing code, you must restart DSH; HMR hot reloading is unreliable in this deployment
  • Uninstalling the plugin via UI will delete the profile’s cordis.patch.yml; recreate this file when reinstalling

Summary

@zimzaza4/dsh-bash-win integrates Git Bash and WSL2 as bash tools for DSH, providing git_bash, wsl_bash, approval, sandboxing, background tasks, and web terminal cards. Usage requires careful attention to default full permissions, sandbox dependencies, and WSL distribution requirements.

Repository URL:

https://github.com/zimzaza4/dsh-bash-win