Introduction

Agents typically run in containers, virtual machines, or CI environments that have no graphical interface. When an automated workflow encounters login, two-factor authentication (2FA), QR-code login, or CAPTCHA, pure headless browser automation breaks down. At the same time, copying Cookies or storageState into these environments is often unreliable, because device-bound credentials, fingerprints, and WebAuthn cannot be migrated directly.

dsh-embedded-browser (formerly dsh-browser-panel) solves this problem. It embeds a browser inside the DSH host and provides an independent tab for each session. The AI controls that tab through browser_embedded_* tools, while humans can view or take over the same tab in real time from the right-side sidebar in the DSH Web UI.

Plugin Overview

Plugin Name: imroc/dsh-browser-panel / dsh-embedded-browser (renamed in v0.3.0)
Maintainer: imroc
License: MIT

This plugin provides a toolset that allows the AI to drive a browser in the background while allowing humans to interact with the page through the sidebar in the Web UI. All sessions share the same persistent profile, so credentials from one login remain valid across all subsequent sessions.

Core Features

The plugin includes 12 tools for controlling, monitoring, and interacting with the browser. These tools use a lazy registration mechanism: they are not registered immediately when the plugin loads, but become available only when specific conditions are met.

Tool List

  • browser_embedded_status: reports status, including the current running state, URL, title, and whether there is a pending operation.
  • browser_embedded_navigate: opens a URL; when used for the first time, it starts the browser; the newTab option can replace the current session’s page.
  • browser_embedded_snapshot: reads a page snapshot and returns the title, URL, a numbered list of clickable/typeable elements, and visible text.
  • browser_embedded_click: clicks by element number or visible text.
  • browser_embedded_type: types text into fields, supporting React/Vue-friendly insertion; the submit parameter presses Enter to submit.
  • browser_embedded_press: simulates key presses, such as Enter, Tab, Escape, arrow keys, and so on.
  • browser_embedded_scroll: scrolls the page, supporting up, down, left, right, and top/bottom directions.
  • browser_embedded_emulate: simulates environment changes, including device presets (such as iphone-14), viewport size (width/height), or dark/light theme (theme). reset: true restores the default settings.
  • browser_embedded_eval: executes JavaScript in the page and returns a limited JSON projection; it can be used to toggle theme attributes, read computed styles, or assert state.
  • browser_embedded_screenshot: captures a PNG image of the page and returns it as an attachment to the model.
  • browser_embedded_ask_human: brings the current session’s browser tab into focus, displays an instruction, and waits for the user to press “I’m done”.
  • browser_embedded_close: closes the current session’s tab; the profile remains unchanged.

Lazy Loading Mechanism

These 12 tools are not registered by default when the plugin is loaded. They are activated in any of the following cases:
1. A successful invocation of the browser-use skill;
2. A human typed /browser-use command;
3. The session logs contain evidence that these tools were successfully invoked previously.

Therefore, without the browser-use skill, these tools will not appear. When installing this plugin, it is recommended to install the browser-use skill as well. Once activated, the tools remain available for the lifetime of the host process, including all sessions created afterward.

In the DSH Web UI, the right-side sidebar can open a “Browser” tab as needed, live-mirroring the tab the AI is operating. The tab supports mouse, wheel, keyboard, and IME input. It is not a screenshot viewer; events are replayed in real time. When human intervention is required, the session tab displays a banner and an “I’m done” button.

Installation and Enablement

Environment Requirements

  • Node.js: >= 22.19
  • DeepSeek Harness (DSH): >= 0.1.5-rc.2

Plugin Configuration

The plugin uses a persistent profile:
$DSH_HOME/embedded-browser/profile

If you are migrating from an older version (0.2.0, formerly dsh-browser-panel), you can preserve the login state by configuring profileDir to point to the old browser-panel/profile directory.

Typical Usage

Use browser_embedded_emulate to simulate a device or theme, then take a screenshot to verify the result:

browser_embedded_emulate { "device": "iphone-14" }
browser_embedded_screenshot

browser_embedded_emulate { "theme": "dark" }
browser_embedded_screenshot

browser_embedded_emulate { "reset": true }

Notes

  • Required Skill: You must install and use the browser-use skill to see the browser_embedded_* tools.
  • Version Compatibility: v0.3.0 corresponds to dsh-embedded-browser, and v0.2.0 corresponds to dsh-browser-panel; the tool prefix is now unified as browser_embedded_.
  • Security: The plugin runs with the permissions of the current DSH process. Please ensure it is installed from trusted sources and check the license.

Summary

dsh-embedded-browser provides graphical interaction capability for agents running in headless environments. By embedding the browser in the host and combining AI-driven automation with real-time human takeover in the sidebar, it solves the pain points of traditional headless automation in scenarios such as login and CAPTCHA.