Introduction

DeepSeek Harness (DSH) allows adding MCP client instances in a profile to invoke browser capabilities. In multi-session or multi-profile scenarios, directly launching multiple browser instances often leads to port conflicts, high memory usage, and mutual interference between processes. The dsh-browser-slotpool plugin introduces a “slot pool” mechanism that explicitly bounds and isolates concurrent browser sessions, resolving the conflicts described above.

What Is This

This is a patch-layer bundle for DSH. It is essentially a browser launcher that wraps the stdio communication of @playwright/mcp. The plugin maintains a fixed-size pool of CDP ports, and each DSH mcp-client instance exclusively owns one slot, ensuring that sessions do not interfere with each other. The plugin itself has no TypeScript source code or build steps, and is ready to use immediately after installation.

Core Features

The plugin primarily provides the following capabilities:
* Slot pool management: Maintains a fixed set of CDP ports (default 9222,9223), operating on a first-come-first-served basis; new connections are rejected when the pool is full.
* Atomic locking and self-healing: Uses the exclusive flag of fs.openSync to implement atomic locking. By checking the liveness of the holder PID, it automatically reclaims locks left behind by abnormally exited processes, avoiding a “all slots busy” deadlock state.
* Idempotent readiness probing: Before launching Chrome, probes whether the port is already open to avoid duplicate launches; it does not kill browsers occupying other slots.
* Ownership isolation: Strictly restricts each mcp-client session to operate only on its assigned slot, with no proxying or stealing.
* Full delegation: Delegates stdio communication entirely to @playwright/mcp, and writes diagnostic logs to stderr to keep the MCP protocol channel unblocked.

Installation and Configuration

To install the plugin, add the dependency from the GitHub repository to the current DSH profile.

  1. Run the following command in the DSH checkout directory (the profile corresponding to the GUI):
    pnpm dsh plugin --profile web add github:bluechips-zhao/dsh-browser-slotpool
  1. After installation, restart the target profile to load the dependency.

Key Configuration Steps

Because !!js is evaluated in DSH without module scope, the launcher path must be specified explicitly through an environment variable.

  1. Find the launcher path after the plugin is installed:
    <DSH_HOME>/profiles/<name>/node_modules/@deepseek-ai/dsh-browser-slotpool/bin/browser-slotpool.mjs
  1. Set this absolute path to the environment variable DSH_BROWSER_LAUNCHER (temporarily or by writing it to a startup script):
    $env:DSH_BROWSER_LAUNCHER = "<DSH_HOME>/profiles/<name>/node_modules/@deepseek-ai/dsh-browser-slotpool/bin/browser-slotpool.mjs"

Optional Environment Variables

The launcher reads the following environment variables to control its behavior:

Variable Name Default Value Description
DSH_BROWSER_PORTS 9222,9223 Comma-separated list of CDP ports contained in the slot pool.
DSH_BROWSER_BASE_DIR LOCALAPPDATA/mcp-shared-browsers Root path for the shared browser data directory and lock files.
DSH_PLAYWRIGHT_MCP_ENTRY (empty) Absolute path to cli.js for @playwright/mcp. If set, Node can be invoked directly, avoiding npx network overhead.
DSH_PLAYWRIGHT_MCP_CMD npx Command used to invoke Playwright MCP (only used when entry is not set).
CHROME_PATH (system detection) Absolute path to the Chrome/Chromium executable.

Usage Example

Add an @deepseek-ai/dsh-mcp-client instance in your profile configuration:

  1. Add the instance in the configuration file.
  2. Set command to point to bin/browser-slotpool.mjs, and set args to an empty array.
  3. Ensure that the DSH_BROWSER_LAUNCHER environment variable correctly points to the launcher path above.

After configuration is complete, the browser tools will appear in the model’s available tools list in the form of mcp__browser__<rawName>.

Local Validation

Run the smoke test script included in the repository to validate the full chain:

node test/mcp-client-smoke.mjs

This script starts a local server, creates a slot, connects to Playwright MCP, and executes a screenshot operation to confirm that a real page is rendered.

Applicable Scenarios and Notes

  • Applicable scenarios: You need to run multiple browser instances simultaneously in a single DSH profile and want strict isolation of resources and ports.
  • Runtime prerequisites:
    • A local Chrome/Chromium browser must be installed.
    • The built-in @deepseek-ai/dsh-mcp-client provided by DSH is required.
    • @playwright/mcp is required (if DSH_PLAYWRIGHT_MCP_ENTRY is not set, the first invocation requires network access to fetch it).
  • Caveats:
    • This is a pure .mjs file with no TypeScript source code; modifications must be made by editing the source file directly.
    • If you change the repository namespace, you must also update the GitHub address in dsh plugin add accordingly.
    • External network access capability depends on the deployment environment (when invoking Playwright MCP via npx).

Conclusion

dsh-browser-slotpool provides a robust concurrent browser solution for DSH through explicit slot management and PID liveness checks. It resolves resource contention in multi-instance environments, making it suitable for developers who need stable multi-session collaboration.

For more details and source code, please visit: GitHub repository