DSH (DeepSeek Harness) adopts an “everything is a plugin” architecture. When an Agent needs to drive Chromium, open tabs, execute scripts, or observe pages during a session, dsh-browser-tool is the core component. It is ported from oh-my-pi’s browser tool, preserves the three-stage open / run / close semantics, and provides Browser Relay mode to take over the user’s local real Chrome.

This repository is now archived, and development has migrated to the mtaech/melon repository.

Installation and Enablement

Before installation, you must first stop any running dsh process. Modifying the dependency tree while the service is running can cause the running process to read incomplete modules.

  1. Install the plugin:
    dsh plugin --profile <你的 profile> add dsh-browser-tool

Or add it directly via npm:

    cd ~/.dsh/profiles/<你的 profile>
    pnpm add github:mtaech/dsh-browser-tool
  1. Register it in the Profile:
    In that profile’s package.json, add the plugin to the dsh.profile.bundles array (it is recommended to place it last):
    {
      "dsh": {
        "profile": {
          "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-browser-tool"]
        }
      }
    }
  1. Configure Sharp:
    Screenshot functionality depends on sharp native modules, and pnpm skips its build scripts by default. It must be allowed in the profile’s pnpm-workspace.yaml:
    allowBuilds:
      sharp: true
  1. Verify:
    After restarting dsh, check whether the configuration took effect:
    dsh --profile <你的 profile> --dump-config | grep dsh-browser-tool

Core Features

open: Browser Source

Four browser sources are supported, launched with action:"open":

  • headless: Launch a headless Chromium in-process, auto-downloaded using puppeteer-core + @puppeteer/browsers, with stealth injection support.
  • spawned: Launch a specified executable detached (desktop app or custom App), attach via an idle CDP port, and reclaim it with the process on close.
  • connected: Connect to an existing CDP endpoint (via environment variable DSH_BROWSER_CDP_URL); it does not own the browser, so release only disconnects.
  • relay: Take over the Chrome instance the user is currently using via the local Browser Relay, with support for tab group queuing and debugger ban recovery.

run: Script Execution

Run JS units in a tab, providing a rich API:

  • Scopes: page, browser, tab (supports goto/observe/ariaSnapshot/screenshot/extract/click/type/fill/press/scroll/drag/waitFor*/evaluate/select/uploadFile/ref, etc.).
  • Output: Supports text stream output, screenshots auto-resized to the model’s pixel budget, and JSON return values.
  • Helper functions: display, print, console, assert, wait, sleep.
  • Error handling: If omp-specific helpers are called (e.g., read/write/env/tree/agent/parallel/pipeline/phase/log/budget), a clear error will be reported.

close: Lifecycle

Close the tab, with the option to also kill the browser process.

relay CLI

Provides local server commands:
* serve: Start an HTTP+WS service and spoof Chrome’s CDP discovery interface.
* install: Install the extension into ~/.dsh/browser-relay/extension.
* status: Check the service status.

Configuration and Environment Variables

Behavior is controlled via DSH_BROWSER_* environment variables (all optional):

  • DSH_BROWSER_ENABLED: Disables the tool when 0.
  • DSH_BROWSER_HEADLESS: Uses headless mode by default when 1.
  • DSH_BROWSER_RELAY / DSH_BROWSER_RELAY_URL: Uses relay mode when 1 (default http://127.0.0.1:9224).
  • DSH_BROWSER_CDP_URL: Default connected target.
  • DSH_BROWSER_SCREENSHOT_DIR: Directory for saving screenshots.
  • DSH_BROWSER_NO_WEBP: Uses PNG for the model copy when 1.
  • DSH_BROWSER_INSTALL_CHROME: Does not automatically download Chromium when 0.
  • DSH_BROWSER_DONOR_CACHE: Additional Chromium reuse sources (e.g., oh-my-pi’s cache).
  • PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE: Specify the Chromium executable.

Dependency Notes

This plugin declares @deepseek-ai/dsh-tools and @deepseek-ai/schemastery as peerDependencies. DSH exposes the host runtime to plugins via a symlink farm. If they are written into dependencies, pnpm will install copies, causing cross-instance module instance reads to be undefined and triggering scheduling errors. Do not write them into dependencies during installation.

Chromium Reuse Strategy

When launching headless Chromium, resolve the executable in the following order:
1. Environment variables PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE.
2. Installed Chrome/Chromium on the system.
3. Existing Chrome for Testing in this package cache.
4. Other tool caches: Copy directly from DSH_BROWSER_DONOR_CACHE, ~/.omp/puppeteer, PUPPETEER_CACHE_DIR, etc., without re-downloading.
5. Only if none of the above are available will it download from Chrome for Testing.

Typical Usage

# 1. 打开一个非 headless 的标签页
browser action:"open" name:"wiki" url:"https://en.wikipedia.org" headless:false

# 2. 在标签页内运行脚本，观察并点击登录
browser action:"run" name:"wiki" code:"await tab.observe(); await tab.click('text/Log in');"

# 3. 关闭标签页
browser action:"close" name:"wiki"

# 4. 启动 Browser Relay 服务
dsh-browser-relay serve

Notes

  • Archived status: This repository is archived; please handle Issues and PRs in the mtaech/melon repository.
  • Permissions: The plugin runs with the permissions of the current dsh process; please review the source code and license.
  • Structure: Core logic is ported from oh-my-pi, including the three-stage open, run, close process and the tab API implementation.

GitHub repository