Introduction

When developing plugins, applying patches, or testing on DeepSeek Harness (DSH), if changes go directly into the main codebase, the impact of a test failure would be much larger. dsh-sandbox-tester is a DSH plugin used to run the changes to be tested in an isolated sandbox first, and then decide whether to merge them back into the main codebase.

Below is an introduction to its positioning, core capabilities, installation methods, typical usage, and considerations.

What is it

  • Repository: Sutera-Diffusus/dsh-sandbox-tester
  • Maintainer: Sutera-Diffusus
  • License: MIT
  • Positioning: Provides a process-level isolated testbed for DSH

The core problem it solves is: plugin or patch changes run first in a sandbox instance to avoid issues during the testing phase directly affecting the main codebase.

Core Features

Process-Level Isolated Sandbox

Each sandbox instance has the following isolation features:

  • Independent process
  • Independent DSH_HOME
  • Independent ports, starting from 3182, automatically +1 on conflict

Each sandbox is cloned by default with approximately 270 MB.

9 Native Tools

dsh-sandbox-tester provides the following tools:

  • sandbox_list: View current sandboxes
  • sandbox_create: Create a sandbox
  • sandbox_inject: Inject the plugin or patch to be tested into the sandbox
  • sandbox_run: Run the sandbox
  • sandbox_health: Check sandbox health status
  • sandbox_stop: Stop the sandbox
  • sandbox_destroy: Destroy the sandbox
  • sandbox_merge: Merge back with a gate
  • sandbox_prune: Clean up sandboxes, suitable for handling stale sandboxes

Merge Gate

sandbox_merge defaults to dryRun, performing only verification and producing results without actual writing. The merge process includes:

  • Target whitelist
  • Per-file node --check
  • bundle verification
  • Backup plan and rollback list

Actual writing requires setting:

DSH_SANDBOX_MERGE_ALLOW=1

If the actual write fails, it will automatically roll back.

One-Click QA

One-Click QA drives headless Edge via CDP 9223 to check the following:

  • Home page
  • /plugins/dsh-sandbox/client.js
  • Settings page “Test Sandbox” section
  • Console exceptions

Check results will generate a report.

Settings Page Management

In the “Test Sandbox” section of DSH Settings, you can:

  • View sandbox cards
  • Create new sandbox
  • View 48h stale sandbox warning
  • One-click clean up
  • View merge gate summary

Termination Safety

sandbox_stop performs a reverse lookup of the 3080 listening PID before executing. If the target process tree contains the main codebase, execution will be refused.

Installation and Enablement

Environment Requirements

  • Operating System: Windows 10/11
  • Node.js: 18+
  • DeepSeek Harness: 0.1.0-rc.6 or same series version

Installation Steps

  1. Obtain dsh-sandbox-tester and confirm the DSH installation directory. The following text uses <DSH_INSTALL_DIR> to represent this directory.

  2. It is recommended to close the DSH page before installation. Then, execute the installation script:

node install.mjs --target "<DSH_INSTALL_DIR>"

The installation script modifies two files in the DSH installation directory: profile manifest and apiproxy whitelist, and backs them up first.

  1. Restart DSH.

  2. Open the Settings page, view the “Test Sandbox” section; then ask the Agent to call sandbox_list to confirm the tool is registered.

Typical Usage

Letting the Agent Execute a Full Test Workflow

You can ask the Agent to execute the following steps in a session:

  1. sandbox_create
  2. sandbox_inject
  3. sandbox_run
  4. sandbox_merge after health check passes

You can also directly state:

Verify this patch using the test sandbox: first sandbox_create, then sandbox_inject, then sandbox_run, and sandbox_merge after the health check passes.

Viewing and Cleaning Sandboxes

Use sandbox_list to view current sandboxes and clean up stale sandboxes.

Running Local Tests

node test/smoke.mjs
node test/e2e.mjs
node test/qa-cdp.mjs <port>

Replace <port> with the target instance port.

Applicable Scenarios and Considerations

Suitable for scenarios involving plugin development, patching, or testing on DSH. Pay attention to the following points before use:

  • Plugins run with the current DSH process permissions. You should check the source code and license before installation. This plugin’s license is MIT.
  • The installation script modifies profile manifest and apiproxy whitelist files, and backs them up first; it is recommended to close the DSH page before installation.
  • sandbox_merge defaults to dryRun; actual writing requires explicitly setting DSH_SANDBOX_MERGE_ALLOW=1, and it will automatically roll back on failure.
  • Each sandbox is cloned by default with approximately 270 MB, so you need to reserve disk space.
  • The plugin does not read or upload user credentials or session data; no telemetry, no external network requests; One-Click QA only connects to the local machine 127.0.0.1.

Summary

The value of dsh-sandbox-tester lies in transforming DSH plugin testing from directly modifying the main codebase to a process of first running in isolation and then merging back with a gate.

  • GitHub Repository: https://github.com/Sutera-Diffusus/dsh-sandbox-tester
  • Community Directory: Search for dsh-sandbox-tester in the DSH Community Directory