dsh-chrome-browser

chrome-browser

A DeepSeek Harness plugin that gives the model a chrome tool: it drives the Google Chrome installed on the machine over the Chrome DevTools Protocol, so front-end work can navigate, screenshot, inspect, and interact with real rendered pages.

The tool runs inside the Harness Host process, which has two consequences worth knowing:

• No per-call approval. A chrome call is an ordinary tool call; it never asks for shell or sandbox permission.
• It is not affected by the shell sandbox. On Linux, Chrome cannot start under a Landlock-confined shell (it aborts with chrome_crashpad_handler: --database is required), so a plain google-chrome --headless … bash command fails on a hardened Host. The Host process is not confined, and the plugin runs there.

Works on Linux, macOS, and Windows: the browser is located per platform, the sandbox flag follows the platform, and Windows process-tree teardown uses taskkill.

Screenshots are returned as real images in the tool result (when the model route accepts image input) and written to a file, so the model sees the rendered UI while a human can open the exact PNG afterwards.

A real render, captured by the tool itself — astro.build at 1280×800:

Tool reference

One tool, chrome, with an action parameter. Page ids (p1, p2, …) come from open; every later action takes an optional page and otherwise uses the most recent one.

Requirements

• Google Chrome or Chromium (any recent version; developed against Chrome 155), on Linux, macOS, or Windows. Chromium-based Microsoft Edge is accepted as a last resort on Windows.
• Node.js 22+ (uses the global WebSocket).
• No npm dependencies: the plugin imports only its sibling module and Node.js built-ins.
• For CJK pages install a CJK font (apt-get install fonts-noto-cjk on Debian/Ubuntu, or the Noto CJK fonts on Windows/macOS); without one, screenshots render those glyphs as empty boxes.

Install into a Harness profile

The Host imports plugins only from its own module roots (the profile and the dsh installation), so the bundle must be installed as a real copy inside the profile, not as a link to a checkout:

npm pack                    # -> local-dsh-chrome-browser-<version>.tgz

Then install that tarball through the Harness plugin manager (plugin_manager, action: install_bundle, target = absolute tarball path). The Host reports restart-required when it replaces an already installed package; restart dsh web to load the new module generation. A version bump changes the dependency spec, which is what makes an update detectable.

Configuration

The bundle patch sets these; apply merges them over its own defaults and validates them.

How Chrome is located

The tool schema has no path parameter: the model never needs to know where the browser lives. resolveChromePath resolves in this order and fails with an actionable message naming the config key when nothing matches:

1. the row's chromePath config;
2. the DSH_CHROME_PATH environment variable;
3. the probe list for the running platform:
   • Linux — /usr/bin/google-chrome, google-chrome-stable, google-chrome-beta, /usr/bin/chromium, chromium-browser, /opt/google/chrome/chrome, /snap/bin/chromium, /var/lib/flatpak/exports/bin/com.google.Chrome;
   • macOS — /Applications/Google Chrome.app/Contents/MacOS/Google Chrome, the Chromium bundle, and the per-user ~/Applications copy;
   • Windows — %ProgramFiles% and %ProgramFiles(x86)% \Google\Chrome\Application\chrome.exe, %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe, then %ProgramFiles(x86)%\Microsoft\Edge\Application\msedge.exe.

For an unusual installation, set DSH_CHROME_PATH for the Host or edit the row's chromePath — no code change is needed.

Platform notes

If Chrome exits before exposing a DevTools endpoint on Windows, the usual causes are a policy block on --remote-debugging-port, antivirus interception, or a profile path the browser cannot use; set userDataDir to a plain ASCII directory to rule out the last one.

Tests

Two dependency-free suites drive real Chrome (no test framework required):

node test/engine.test.mjs   # CDP engine: browser resolution per platform, navigation, capture, input, console, network, teardown
node test/tool.test.mjs     # the real tool definition: schema validation, every action, error paths

Run them from the repository root; tool.test.mjs writes throwaway screenshots under .tmp/. Browser resolution is injectable, so the Linux/macOS/Windows probe lists are covered even when the suite runs on one of them.

Operational notes

• Chrome starts lazily on the first action and runs with a fresh temporary profile; stop (or plugin disposal) terminates it and removes that profile. With userDataDir set, that directory is left in place instead.
• One Chrome process is shared by all pages, and all sessions share it.
• Captures beyond 12000 CSS px of page height are capped, and a clip capture that exceeds the deployment's image limits is retried once at half scale.
• If no attachment service or image-capable route is available, screenshot still saves the PNG and reports the path instead of attaching the image.

License

MIT — see LICENSE.