Preamble

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” In agent development, there are cases where the model needs to directly operate a browser environment. The dsh-browser plugin connects DSH to the user’s browser tabs through a companion Chrome/Edge MV3 extension, enabling it to read page content and perform interactive operations.

Components and Architecture

In production, the plugin uses a three-layer architecture and communicates via WebSocket and Native Messaging:

  1. DeepSeek Harness: Runs in the DSH environment and provides browser_* tools and a Web settings card.
  2. Native Messaging Host: A local executable responsible for validating the extension ID, forwarding messages, and completing authentication.
  3. Chrome/Edge MV3 extension: Installed in the browser, responsible for observing pages, displaying control status, and executing specific browser actions.

Installation and Enablement

Installing the plugin requires the following prerequisites: Node.js 22.19 or later, and a Chrome, Chromium, Edge, or Brave browser that supports MV3 and Native Messaging.

1. Install the Harness plugin

Install the plugin into the Web profile:

dsh plugin --profile web add github:justwe-bot/dsh-browser

2. Prepare the extension directory

Run the script included in the installation package to package the extension under DSH_HOME:

dsh plugin --profile web exec dsh-browser-native-install --prepare-extension

This command prints the extension directory path, usually $DSH_HOME/browser-extension.

3. Obtain the extension ID

  1. Open chrome://extensions in the browser (or the corresponding page in Edge/Brave).
  2. Enable “Developer mode”.
  3. Click “Load unpacked extension” and select the directory printed by the previous command.
  4. Copy the displayed 32-character extension ID.

4. Install the Native Messaging host

Use the obtained ID to install the native host:

dsh plugin --profile web exec dsh-browser-native-install \
  --extension-id <extension-id> \
  --browser chrome

This writes the host executable to $DSH_HOME/browser-native-host/ and generates the configuration file browser-native-host.env.

5. Start Harness

In the shell that starts Harness, load the generated environment variables:

source ${DSH_HOME}/browser-native-host.env && dsh web

6. Configure and verify

  1. Open DSH’s Settings > Plugins > Plugin configuration > DSH Browser.
  2. Confirm that the extension popup shows the status as Connected.
  3. Ask the agent to list the browser tabs to verify the connection.

Tool List

The plugin registers the following tools by default, which are available in the agent’s tool catalog:

  • Observation: browser_list_tabs (list tabs), browser_snapshot (take a snapshot), browser_wait (wait).
  • Tabs and navigation: browser_new_tab (create a new tab), browser_navigate (navigate), browser_back, browser_forward, browser_reload.
  • Page operations: browser_click (click), browser_type (type), browser_scroll (scroll), browser_key (keypress).
  • Script evaluation: browser_evaluate. If this tool is not needed, set browser-tools.config.enableEvaluate: false in the configuration.

Notes

  • Direct mode: This mode is intended only for local development and diagnostics, and is not suitable for production environments.
  • Permission limitations: Model tools cannot activate a tab or focus the browser window. browser_new_tab always opens a background tab.
  • Page limitations: Only HTTP/HTTPS pages are supported. Browser internal pages, extension pages, and file: URLs are not supported.
  • Element references: Element references in a snapshot are valid only under the current snapshot’s documentId. After navigation or document replacement, the references become invalid (returns STALE_REF).
  • Approval mechanism: Mutating tools (such as click and type) require approval under the default workspace-write permission. Under the danger-full-access policy, no prompt is required, but HTTP/HTTPS restrictions still apply.
  • Environment variables: DSH refuses to load sensitive DSH_* variables from $DSH_HOME/.env; they must be loaded through a dedicated .env file.

Conclusion

dsh-browser provides DeepSeek Harness with the ability to directly control a browser, integrating it into the model context, session logs, and approval workflow. Developers can follow the steps above to install and configure it, and build agent applications that require direct web page operations.