Preface¶

In DSH’s plugin mode, browser capabilities can be integrated into the Agent’s tool pipeline as native tools. dsh-cloak-browser addresses the scenario where: when an Agent needs to open pages, complete interactions, and read rendered results, the browser session state is preserved within DSH’s tool calls, and an isolated BrowserContext is maintained for each Agent. Page state is returned as bounded snapshots and short references, allowing the Agent to continue executing subsequent actions based on these references.

What This Is¶

maxiaovivi/dsh-cloak-browser is a DSH plugin package maintained by maxiaovivi, positioned as:

Native CloakBrowser tools for DeepSeek Harness with per-agent browser sessions and snapshot references.

It integrates DSH with CloakBrowser: the DSH side handles Agents, tool calls, and attachment capabilities, while the CloakBrowser side handles browser startup, input, and browser binary distribution. Verified sources clearly state that this repository is not an official DeepSeek or CloakHQ project and does not represent endorsement by either organization.

Core Capabilities¶

The following are the main capabilities listed in the verified sources:

• Native DSH tools: Provides schema, canonical JSON results, UI presentation, and Code Mode compatibility.
• Lazy browser startup: Chromium only launches when the Agent invokes browser tools.
• One isolated BrowserContext per Agent: The corresponding context is automatically closed when the Agent ends or the plugin is unloaded.
• Automatic bounded page snapshots: Returns bounded page snapshots after navigation and interaction, accompanied by short-lived element references, e.g., p1:s3:e8.
• Browser tools cover navigation, click, fill, select, keyboard, wait, extraction, screenshot, tab, and lifecycle.
• Durable DSH image attachments: Saves image attachments for image-capable models; text routing uses text snapshot fallback.
• Optional humanized mouse, typing, and scrolling, provided via CloakBrowser.
• Automatic license-plan detection: A verified Free key can launch directly without user confirmation; concurrent local Free-session launches within the same DSH process are serialized.
• Proxy-aware GeoIP consistency: Automatically enabled when proxy environment variables exist; its runtime dependencies are bundled.
• Domain allow/deny rules, explicit local/private-address blocking, page and output limits, cooperative cancellation, and browser cleanup.
• A resident routing prompt: Routes the browser to rendered or interactive tasks; simple public text lookups continue to use lighter-weight web search/fetch tools.

Installation and Enablement¶

Prerequisites¶

The requirements listed in the verified sources include:

• Node.js 20 or newer
• DeepSeek Harness (DSH) 0.1.0-rc.6
• The package.json in the retrieved source shows version 0.3.0
• peerDependencies are @deepseek-ai/dsh-llm ^0.1.0-rc.6 and @deepseek-ai/dsh-tools ^0.1.0-rc.6

Installing from GitHub¶

First, add the plugin:

dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

Then confirm the plugin is composed into the profile:

dsh --profile web --dump-config | grep -A24 cloak-browser

Restart DSH to activate the plugin:

dsh --profile web

The commands above follow the example profile web from the verified sources. If your current DSH environment uses a different profile, adjust the profile name in the commands according to your actual environment.

Optional Environment Variables¶

The license key and proxy address should not be written into cordis.patch.yml or tool parameters. The sources require exporting them into the environment where DSH is launched:

export CLOAKBROWSER_LICENSE_KEY='your-license-key'       # optional
export CLOAKBROWSER_PROXY_URL='http://user:pass@host:port' # optional
dsh --profile web

Free Key and Keyless Paths¶

If no license key is present, CloakBrowser selects its available free build. The first browser use downloads and verifies a Chromium archive of approximately 200 MB. The extracted cache may occupy significantly more disk space under ~/.cloakbrowser. The sources explicitly state that there is no need to run playwright install chromium.

A verified Free key launches directly without requiring user confirmation. Concurrent local Free-session launches within the same DSH process are serialized. The plugin cannot revoke sessions belonging to other machines or abnormally leftover processes.

Proxy and GeoIP¶

When a proxy URL is present, the plugin automatically enables CloakBrowser’s GeoIP matching. On first use, it may download a GeoLite database of approximately 70 MB, placing it in the same cache directory.

Migration from Older Versions¶

The verified sources explain that versions 0.1.1 and later reuse existing dsh-tools and dsh-llm runtime instances in the profile. If you previously installed 0.1.0, you need to uninstall once before reinstalling:

dsh plugin --profile web remove -w dsh-cloak-browser
dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

Restart DSH after completing the steps.

Uninstallation¶

Execute:

dsh plugin --profile web remove -w dsh-cloak-browser

Then restart DSH. The sources note that the cached browser binaries under ~/.cloakbrowser are managed separately by the CloakBrowser CLI.

Typical Usage¶

The recommended workflow from the verified sources is as follows:

browser_open(url)
  → Free, paid, or keyless: launches directly without asking
  → occupied Free seat: returns not_started without retrying in a loop
  → returns snapshot + refs
  → browser_click / browser_type / browser_select → returns next snapshot + refs
  → browser_close when the browser task is complete

In other words, the Agent first opens the target page, and the plugin returns a page snapshot and short references; the Agent then executes clicks, inputs, or selections based on these references; each interaction returns the next round of snapshots and references; after the task is complete, browser_close is called to end the browser task.

For image-capable models, the plugin uses Durable DSH image attachments; for text routing, it uses text snapshots as a fallback.

Applicable Scenarios and Considerations¶

Suitable Scenarios¶

• The Agent needs to open rendered pages and complete interactions.
• Clicks, fills, selects, keyboard input, waits, extractions, screenshots, tab management, and browser lifecycle management are required.
• Isolating browser state for multiple Agents within DSH to prevent cross-Agent leakage is desired.
• Browser tools should return structured snapshots and short references rather than having the Agent maintain large volumes of page DOM.
• Simple public text lookups should be left to lighter-weight web search/fetch tools via routing prompts.

Considerations Before Use¶

1. This plugin runs in the environment where DSH is launched and uses the permissions available to the current DSH process. Before installation, review the source code, policies, tool boundaries, and licenses.

2. Regarding the license type, the verified sources only indicate that the files in package.json lists a LICENSE filename, but no specific license type is provided. Do not treat it as a confirmed MIT, Apache, or other license.

3. Credentials should not be placed in cordis.patch.yml or tool parameters; they should be exported into the environment where DSH is launched.

4. First use may cause significant disk usage: the keyless path downloads approximately 200 MB of Chromium archive on first use; the proxy path may download approximately 70 MB of GeoLite database on first use.

5. Free-session occupancy status only applies to local concurrency scenarios. Sessions held by other machines or abnormally leftover processes cannot be revoked.

6. This repository is a community-maintained project, not an official DeepSeek or CloakHQ project, and does not represent endorsement by either organization.

Conclusion¶

The core of dsh-cloak-browser is transforming CloakBrowser’s browser capabilities into native DSH tools: isolating browser contexts per Agent, returning bounded snapshots and short references, while preserving capabilities such as navigation, interaction, screenshots, attachments, proxy GeoIP, Free-session serialization, and security boundaries.

GitHub repository address:

https://github.com/maxiaovivi/dsh-cloak-browser