dsh-browser/packages/browser/bridge-browser

One-Line Positioning

This plugin is the browser operation bridge for dsh web profile: mounts a token-authenticated WebSocket channel on the host webserver, allowing the Chrome extension to connect in and read and operate the page you are browsing, with login state and session preserved throughout.

Core Capabilities

• Read structured text snapshots of the current tab (title, URL, body, numbered interaction list, and sanitized form fields)
• Click elements by number, append or replace text in input boxes, send keyboard keys (Enter/Tab/Escape/Arrow keys, etc.)
• Scroll viewport up/down, jump to top or bottom, scroll by pixels
• Navigate to any HTTP(S) address within the current tab, as well as forward, backward, refresh
• Read plain text from any page area or selector
• Wait for page load and DOM changes to stabilize, with optional additional delay

Technical Implementation

• Language: TypeScript
• Key Dependencies: @deepseek-ai/schemastery (config schema), ws (WebSocket server), @deepseek-ai/dsh-tools (tool registration), @deepseek-ai/dsh-host-webserver (mount upgrade route)
• Architecture Pattern: Cordis plugin, injected into dsh's web profile via dsh.bundle.patch; the plugin registers /ext/bridge WebSocket upgrade route and /ext/bridge-config HTTP endpoint on webServer, and pumps session events per connection via ctx.apiProxy.events.mux; browser_* tools are registered on ctx.tools, each execution dispatches tool.call frames to the extension via WebSocket
• Entry File: packages/browser/bridge-browser/src/index.ts

Use Cases

Suitable for directly operating already-logged-in webpages within dsh (e.g., admin dashboards, SaaS consoles, multi-step flows requiring cookie preservation). DSH models lack visual capabilities, so this plugin provides a pure-text "read page + click/fill by number" toolchain, letting the model complete tasks in the user's own Chrome rather than launching a headless browser. Privacy-sensitive everyday users can also use it for form filling, content extraction, and cross-page navigation.

Prerequisites & Compatibility

This plugin declares no additional native module dependencies.

Installation

dsh plugin --profile web add github:Lum1104/dsh-browser/packages/browser/bridge-browser

For complete installation (Chrome extension build and load), use the repository's install script: curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash. This command alone only registers the bridge plugin; the extension needs to be built separately and loaded into Chrome.

Configuration Options

Environment variable DSH_EXT_TOKEN can inject token, and DSH_BROWSER_SESSION_WORKSPACE can override the session workspace path (same name as field above, equivalent).

FAQ

Q: After installation, the sidebar keeps showing "Not Connected"?

A: The dsh plugin command only registers the bridge bundle to the local web profile; if dsh was already running before installation, it won't auto-load the new plugin. Stop the current dsh process and re-run pnpm start or npx @deepseek-ai/dsh web, the extension will automatically detect the bridge address via /ext/bridge-config and reconnect, no reconfiguration needed.

Q: Do I need to manually copy-paste the Token?

A: Local (127.0.0.1) loopback connections don't require a Token; the extension directly gets the WebSocket address via /ext/bridge-config and connects. Only when using --host 0.0.0.0 to make dsh listen on non-loopback addresses do you need to fill in the Token in the sidebar settings.

Q: Which webpages cannot be read or operated?

A: Protected browser built-in pages (such as chrome://, chrome-extension://, Chrome Web Store) cannot have content scripts injected, so this plugin doesn't support them; only regular http:// or https:// pages work. Already-opened pages don't need refreshing; the extension will automatically inject the script on first operation.

Q: Will passwords or bank card numbers be sent to the model?

A: No. Sensitive fields (type=password and payment card numbers) are rendered as •••• in the page snapshot, with values never leaving the page; form fill results only return sanitized plain text.

Q: Will the model follow when I switch tabs?

A: No. When the assistant starts working, it binds the context to the currently active tab; after the user manually switches away, subsequent browser operations pause, with the sidebar asking whether to "Continue on original page" or "Follow new page". Choosing the original page allows background operations but will never change the tab you're viewing.

Q: What's the relationship with dsh's official browser capabilities?

A: This is the browser capability implementation for dsh web profile: the plugin registers browser_* toolset + WebSocket channel, the model addresses by number to execute actions in the user's own Chrome, with all login state and session preserved throughout.

Q: How to uninstall?

A: Execute dsh plugin --profile web remove @yuxianglin/dsh-bridge-browser on the dsh side to remove the bridge plugin; on the Chrome side, go to chrome://extensions, find "dsh Browser Assistant", and click "Remove". Local copies at ~/.dsh/dsh-browser (managed installation) and ~/.dsh/browser-extension (extension directory) can be cleaned up as needed.

Getting Started Difficulty

Beginner — Users basically don't need manual configuration: after installing the bridge + Chrome extension, opening the sidebar works immediately; only when debugging or customizing Token, timeout, or snapshot limits should they revisit the configuration options.

Known Issues & Limitations

• Only one extension connection allowed at a time; newly opened windows replace the old one, and pending tool calls in the old window fail with bridge-closed
• Protected or destroyed cross-origin iframes are marked as "unavailable" in snapshots, but don't cause the entire page snapshot to fail
• Token has no automatic expiration mechanism; you need to manually change ~/.dsh/ext-bridge-token or change token in config to rotate
• /ext/bridge-config only returns ws://127.0.0.1 address; non-loopback deployment requires manually entering address and Token in sidebar settings
• The repository's Playwright e2e automatically skips when there's no available Chromium or the extension isn't built, which doesn't affect the bridge itself
• Approval logic is forced to execute in the extension service worker, not relying on model self-discipline; the DSH tool pipeline hasn't opened the same strategy to other clients yet

English | 中文

Connect DeepSeek Harness to the Chrome tab you are already using. The model can read page content, click controls, fill forms, scroll, and navigate while preserving your login state, session, and cookies. A side panel provides the conversation UI.

dsh is DeepSeek AI's open-source, plugin-based agent harness. This repository provides a companion browser bridge plugin and Chrome MV3 extension as one standalone pnpm workspace.

The integration is text-only: pages become structured text with a numbered inventory of interactive elements, and the model addresses those elements by number. Screenshots never enter the model-facing pipeline.

Quick install

The standard dsh plugin command alone cannot install this project. The integration contains both a dsh bridge plugin and a Chrome MV3 extension, and the extension must also be built and installed in Chrome. Use the repository's one-line installer to set up both parts:

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash

When the installer opens chrome://extensions, follow its instructions to load or reload dsh Browser Assistant. If dsh is already running, restart it after installation. See Detailed installation and usage for prerequisites, startup commands, updates, and developer installation.

[!IMPORTANT] The unscoped dsh-browser package on npm belongs to a different project and is not affiliated with this repository. This project is not currently published as an npm package; use the installer above.

Performance

In a paired 60-run end-to-end benchmark on August 18, 2026, both backends completed all 30 assigned runs successfully, while dsh Browser Control required fewer model/tool round trips and finished faster:

The paired Playwright / extension duration ratio was 1.24 (95% CI 1.16–1.34): Playwright took about 24% longer, or equivalently, dsh Browser Control reduced latency by about 20% and saved 1.35 seconds per task on average. The suite used six browser tasks, five deterministic seeds, the same DSH profile and model (deepseek-v4-flash), and independently validated page state. See the benchmark methodology and reproduction guide.

Core capabilities

Repository layout

packages/browser/bridge-browser/
  cordis.patch.yml
extensions/dsh-browser/
scripts/install.sh

Why this design

• Your real browser, not a headless copy: the model works in the page you already have open, retaining logins, sessions, and cookies.
• A text-first model interface: numbered controls, stable IDs across snapshots, delta updates, and masked sensitive values make pages operable without vision.
• A narrow privacy boundary: passwords and payment-card values are always rendered as •••• and never leave the page.
• A guarded bridge: authenticated handshakes protect remote connections, privileged gateway methods reject non-loopback callers, and the extension binds tools to one user-controlled tab.

Detailed installation and usage

Requirements: Node.js ^22.19 or >=24, Corepack/pnpm, and Google Chrome.

Install or update

For a managed installation, run:

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash

The installer downloads main, builds and registers the bridge plugin, builds the Chrome extension into ~/.dsh/browser-extension, and opens chrome://extensions. On the first install, load that directory as an unpacked extension; on updates, click Reload. Restart dsh if it is already running.

To install the current branch from a source checkout instead:

git clone https://github.com/Lum1104/dsh-browser.git
cd dsh-browser
./scripts/install.sh

After pulling or switching revisions, rerun ./scripts/install.sh and reload the extension.

Start and use

Start the managed installation with:

cd ~/.dsh/dsh-browser && pnpm start

From a source checkout, run pnpm start in the repository root. To use the latest public dsh release instead:

npx @deepseek-ai/dsh web

Local use requires no configuration. Open an http:// or https:// page, click the DeepSeek whale icon, and wait for Connected. Existing tabs are instrumented on the first action; protected pages such as chrome:// and the Chrome Web Store are not supported.

Troubleshooting

Side panel stays "Not connected"

• Make sure dsh web is running locally (default http://127.0.0.1:3080).
• Verify the bridge is loaded: open http://127.0.0.1:3080/ext/bridge-config. It should return JSON such as {"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}. If it returns a web page instead of JSON, the running dsh predates the bridge registration — restart dsh and refresh the page; the extension reconnects on its own.
• The extension probes ports 3080, 3081, and 3090 automatically. If dsh runs on another port — or you use a remote --host 0.0.0.0 deployment — set the address (and bridge token) in the side panel settings.

Development

The bridge plugin and Chrome extension are both members of this repository's workspace. Run all commands from the repository root. For the first development installation, run pnpm install.

pnpm run build
pnpm run typecheck
pnpm run test

pnpm --filter @yuxianglin/dsh-bridge-browser run build
pnpm --filter @yuxianglin/dsh-bridge-browser run typecheck
pnpm --filter @yuxianglin/dsh-bridge-browser run test

pnpm --filter dsh-browser-extension run build
pnpm --filter dsh-browser-extension run test

Notes:

• The bridge plugin must have a built lib/ before startup because the loader consumes it; both scripts/install.sh and the root pnpm run build build the plugin before the extension.
• The dependencies of @deepseek-ai/dsh and the bridge plugin are pinned to the same tested public release line. An upgrade must update the manifests and lockfile together and rerun the root checks.

Security

• The bridge path sits outside the /api trust boundary and performs its own bearer-token authentication.
• Privileged gateway methods such as settings.*, credentials.*, and host.open* reject non-loopback sources.
• The model-facing pipeline is text-only; passwords and payment-card values never leave the page.
• When work begins, the assistant binds to the active tab (at prompt submission, or at the first direct browser-tool call). If you switch tabs manually, later browser actions pause and the side panel asks whether the assistant should continue on the original tab or follow the new one. Choosing the original tab permits background operation; the extension never silently retargets or changes your visible tab. Closing the controlled tab also pauses tools until you explicitly select the current page.
• Page-authored text is wrapped as untrusted input. The default auto mode reads only the controlled tab without an extra prompt; privacy-sensitive users can select ask for per-read confirmation or off to block reads entirely. In ask mode, the read dialog can allow one read or persistently switch back to auto; this can be reversed in Settings. Read page text is sent to the selected model.
• Click, type, keypress, navigation, history, and reload calls fail closed until the user approves them. An origin may be trusted for the current side-panel session (cleared when the last panel closes or the service worker restarts), while permanent trust is managed explicitly in Settings. Explicit cross-origin browser_navigate calls and unknown history destinations always prompt again.