Introduction

If you are developing agents using DeepSeek Harness (DSH), model shell commands run on the host machine by default, with the isolation boundary depending on the executor implementation. On Windows, there is an additional historical baggage: early implementations used cmd /c to launch npm .CMD shims, causing the host shell to parse &, quotes, and %VAR% in model commands first. To achieve “commands executing in a hard-isolated environment without argv being wrapped by the host shell,” a cleaner solution is needed.

The dsh-sandbox-micro introduced below is a plugin bundle prepared for this: it replaces the visible ctx.shell with a bash -c executor in a Linux micro-VM (microsandbox), while retaining a provider directly facing the ctx.sandbox seam.

What is it

omdsh-dev/dsh-sandbox-micro is a plugin package in the DSH ecosystem, npm package name @deepseek-ai/dsh-sandbox-micro, MIT licensed, current version 0.0.1 (marked private: true in package.json). It solves the problem: making shell commands issued by the model execute in a microVM instead of directly falling onto the host, and preferring to reject execution over falling back to an unisolated mode when startup probes fail.

Security Model: Fail-Closed and Shell-Free argv

The plugin’s security design focuses on three points:

  1. Fail-closed startup probe. Before the first confinement, it probes msb --version and msb doctor (the latter checks host virtualization prerequisites); upon failure, it caches the verdict and throws SANDBOX_UNAVAILABLE, never falling back to unisolated execution.
  2. Shell-free argv construction. Instead of using cmd.exe or other shell wrappers for untrusted argv, it directly runs the microsandbox’s built-in Node shim and explicitly rejects .CMD / .BAT paths.
  3. Default disconnected network. It defaults to adding --no-net; network access is explicitly enabled via allowNetwork: true.

Additionally, runner failures during execution are identifiable: runnerFailureRules are calibrated to the real stderr dialects of msb 0.6.15, covering image pulling, mount paths, sandbox startup, and invalid configuration errors.

Two Cordis Entrypoints

This package exposes two Cordis entrypoints with different responsibilities:

Entrypoint Service Purpose
@deepseek-ai/dsh-sandbox-micro ctx.sandbox A compatibility provider that directly calls SandboxProvider.confine(). The seam does not carry env/cwd, so the guest is fixed to /work
@deepseek-ai/dsh-sandbox-micro/shell ctx.shell The actual executor used by the model shell tool. It sees the full ShellExecSpec, maps workdir to /work/<sub>, and forwards ENV_OVERRIDES, spec.env, and DSH_* via -e KEY=VALUE

The accompanying cordis.patch.yml performs four tasks: disables official sandbox / bash-sandbox / pwsh-sandbox, inserts sandbox-micro and shell-micro, enables tool-bash across all platforms, and disables tool-pwsh (PowerShell dialects cannot run in a Debian guest).

Installation and Verification

Prerequisites:

  • Node ^22.19.0 || >=24.0.0
  • microsandbox 0.6.15+ (installed as a dependency with the package)
  • Windows requires Windows Hypervisor Platform; Linux/macOS requires msb-supported local backend
  • The image must contain the program being wrapped; the default debian already includes bash and common coreutils

Recommended installation method is Profile Bundle:

dsh plugin --profile web add github:omdsh-dev/dsh-sandbox-micro
dsh plugin --profile headless add github:omdsh-dev/dsh-sandbox-micro

The package’s dsh.bundle.patch automatically joins the profile layer stack after installation, no manual patching required. Local packaging installation is also possible:

npm pack
dsh plugin --profile web add ./deepseek-ai-dsh-sandbox-micro-0.0.1.tgz

After the steps above, confirm that the configuration is effective and the executor has indeed switched successfully with two commands:

dsh --profile web --dump-config | grep -E 'sandbox-micro|shell-micro'
dsh run "运行 bash 命令验证"

Configuration Options

shell-micro inherits all fields from dsh-bash-local and adds the following fields (the same set of microsandbox fields used by sandbox-micro):

Field Default Description
image debian The OCI image used by the guest
memory 512M VM memory
msbPath "" Executable file override; leave empty to use the built-in microsandbox Node shim
timeout Not set msb run --timeout, e.g., 60s
extraFlags [] Additional msb run flags, e.g., ["--cpus", "2"]
allowNetwork false When true, removes --no-net
probe doctor Startup probe level: doctor or version

Policy Mapping and Known Boundaries

The mapping relationship from Sandbox policy to the guest is as follows:

Sandbox mode Guest file effect Network
read-only workspace mounted to /work with :ro Disabled by default
workspace-write workspace mounted to /work read-write Disabled by default
danger-full-access Does not enter VM (bypassed by caller) —

There are four boundaries to be clear about before use:

  • The guest root file system and /tmp are independent writable layers per command, discarded after exit; policy semantics target effects on the host files.
  • ShellExecSpec.workdir must be within sandboxPolicy.workspaceRoot, otherwise execution is rejected.
  • Only the bash shell is provided; PowerShell tools are disabled via patch.
  • The file paths visible to the model switch from host paths to the Linux /work view; file tools still operate on host paths, which stay in sync via the workspace mount.

If you want to modify this plugin, first run npm run check (typecheck + unit tests + build), then run npm run test:e2e (optional, smoke tests that actually start the microVM).

Use Cases and Considerations

This plugin suits two scenarios: DSH users who want microVM-level isolation for model shell commands, and teams on Windows who want to avoid the host shell parsing model argv. Note that under the danger-full-access policy, the VM is not entered (bypassed by the caller), so the isolation benefit does not apply.

Finally, a reminder: the plugin runs with the permissions of the current dsh process; you should check the plugin source code and license before installing (this project is MIT); also, since the current version is 0.0.1, it is recommended to run an e2e smoke test before going into production to confirm your host virtualization environment is available.

Summary

dsh-sandbox-micro applies the replaceable executor mechanism of DSH to the isolation layer: fail-closed startup probe, argv construction without shell wrapper, default disconnected network, plus clear policy mapping, making the execution boundary of model shell commands predictable.