dsh-browser-use

Readme

# dsh-browser-use

> Browser Use bridge for DeepSeek Harness: let your `dsh` agent run real web tasks — open pages, click, type, fill forms, extract data — through the [Browser Use](https://github.com/browser-use/browser-use) Cloud API.

[![CI](https://github.com/zoahdev/dsh-browser-use/actions/workflows/ci.yml/badge.svg)](https://github.com/zoahdev/dsh-browser-use/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

English | [中文](#中文)

## What it is

A thin, honest bridge. It registers one model-facing tool, `browser_use_run`,
forwards the task to Browser Use's cloud endpoint, and returns the raw run
result. It does **not** reimplement Browser Use and does **not** claim to be a
full integration.

## Install

```sh
dsh plugin --profile web add dsh-browser-use
```

Then set your Browser Use API key (config `apiKey`, or the `BROWSER_USE_API_KEY`
env var).

## Two modes: cloud vs. local

| Mode | Needs | Tools you get |
| --- | --- | --- |
| **Cloud** (this plugin) | Browser Use API key | `browser_use_run` |
| **Local** (free, no key) | Python + `browser-use` installed | `mcp__browser_use__browser_exec`, `mcp__browser_use__browser_screenshot` |

### Local mode (no Browser Use API key)

Browser Use also runs locally as an MCP stdio server — no cloud subscription.
DeepSeek Harness already ships `@deepseek-ai/dsh-mcp-client`, so you do **not**
need this plugin for the local path. Install Browser Use once
(`pip install 'browser-use[cli]'`), then add this to your profile's
`cordis.yml`:

```yaml
- insert:
    - id: browser-use-local
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: browser_use
        transport: stdio
        command: browser-use
        args: ['--cli-mcp']
        cwd: !!js process.cwd()
```

That registers `mcp__browser_use__browser_exec` and
`mcp__browser_use__browser_screenshot`. A ready-to-copy file is in
[`examples/local-mcp.cordis.yml`](examples/local-mcp.cordis.yml).

## Tool

| Parameter | Type | Description |
| --- | --- | --- |
| `task` | string | The task, e.g. "Find the stars of the browser-use repo". |
| `model` | string | Optional provider-prefixed model id, e.g. `openai/gpt-5.5`. |

Returns `{ result }` — the raw Browser Use run result.

## Config

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `apiKey` | string | *(env)* | Browser Use API key |
| `baseUrl` | string | `https://api.browser-use.com` | Cloud API base URL |
| `timeoutMs` | number | `300000` | Request timeout |
| `model` | string | *(none)* | Default model |

## Verified

- `pnpm typecheck` · `pnpm build` · `pnpm test` (4 tests, mocked HTTP).
- Tested with `@deepseek-ai/dsh-tools ^0.1.0-rc.6`.

## Honest limits

- This is a cloud-API bridge; it needs a Browser Use API key.
- Local mode is provided by DeepSeek Harness's own `mcp-client`, not by this
  package; this README documents both so you can pick the cheaper path.
- It returns the raw response; it does not stream or poll for completion.
- Community plugin, not an official Browser Use or DeepSeek product.

---

# 中文

> 给 DeepSeek Harness 的 Browser Use 桥接：让 `dsh` agent 通过 Browser Use 云
> API 执行真实网页任务（打开页面、点击、输入、填表、抽取数据）。

注册一个 `browser_use_run` 工具：把任务转发给 Browser Use，返回原始运行结果。
这是薄桥接，不重新实现 Browser Use，也不冒充官方。

```sh
dsh plugin --profile web add dsh-browser-use
```

需要配置 Browser Use API key（`apiKey` 配置项，或环境变量 `BROWSER_USE_API_KEY`）。

## 两种模式：云端 vs. 本地

| 模式 | 需要 | 得到的工具 |
| --- | --- | --- |
| **云端**（本插件） | Browser Use API key | `browser_use_run` |
| **本地**（免费，无需 key） | Python + `browser-use` 已安装 | `mcp__browser_use__browser_exec`、`mcp__browser_use__browser_screenshot` |

### 本地模式（无需 Browser Use API key）

Browser Use 也能以本地 MCP stdio 服务运行，无需云订阅。DeepSeek Harness 已经内置
`@deepseek-ai/dsh-mcp-client`，所以本地路径**不需要本插件**。先安装一次
Browser Use（`pip install 'browser-use[cli]'`），然后把你 profile 的
`cordis.yml` 加上：

```yaml
- insert:
    - id: browser-use-local
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: browser_use
        transport: stdio
        command: browser-use
        args: ['--cli-mcp']
        cwd: !!js process.cwd()
```

这会注册 `mcp__browser_use__browser_exec` 和
`mcp__browser_use__browser_screenshot`。现成可复制的文件在
[`examples/local-mcp.cordis.yml`](examples/local-mcp.cordis.yml)。