Kimi WebBridge for DeepSeek Harness
Give your DeepSeek Harness agents the user's real browser — with their login sessions.
A third-party plugin bundle for DeepSeek Harness (dsh). It turns the local Kimi WebBridge daemon into 15 native kimi_webbridge_* tools — the agent can open pages, read them, click, type, screenshot, run JS, inspect network traffic, upload files, and save PDFs in your real browser, logged in as you.
✨ What it does
| |
|---|
| 🧭 Real browser, real sessions | The model drives your actual browser — cookies, logins and all. No scraping, no headless shell. |
| 🛡️ Local-only | Everything happens on your machine: plugin → 127.0.0.1:10086 daemon → your browser. No third-party service sees your traffic. |
| 📦 One file, no build | Pure ESM, zero runtime dependencies beyond the harness's own packages. No TypeScript, no transpile, no API keys. |
| 🔌 Standard Cordis bundle | name / inject / apply + defineTool — the exact pattern the shipped harness tools use. Never touches the dsh installation. |
| 🗂️ Tab groups like the product | One session = one tab group; the model names the group in your language on first use and closes it only when you ask. |
🛠️ What the model gets — 15 tools
| Tool | Purpose |
|---|
kimi_webbridge_navigate | Open a URL (new tab or current), set the tab-group label on first use |
kimi_webbridge_find_tab | Re-select a task tab by URL; active:true borrows the tab you're viewing |
kimi_webbridge_list_tabs | List the task's tabs |
kimi_webbridge_snapshot | Read the page as an accessibility tree with @e element refs |
kimi_webbridge_click | Click an element (@e ref or CSS selector) |
kimi_webbridge_fill | Type into inputs, textareas and contenteditable rich editors |
kimi_webbridge_evaluate | Run JavaScript in the page (async supported) |
kimi_webbridge_cdp | Raw chrome.debugger passthrough (advanced escape hatch) |
kimi_webbridge_screenshot | Screenshot the tab or one element; returns a file path |
kimi_webbridge_network | Capture / inspect the tab's network requests |
kimi_webbridge_upload | Upload files to a <input type=file> |
kimi_webbridge_save_as_pdf | Render the current page to PDF; returns a file path |
kimi_webbridge_close_tab | Close the current tab |
kimi_webbridge_close_session | Close the whole tab group — only when you ask |
kimi_webbridge_start_daemon | Auto-start the local daemon when unreachable |
✅ Requirements & versions
| Component | Version |
|---|
DeepSeek Harness (dsh) | 0.1.0-rc.8 (tested) — any build shipping @deepseek-ai/dsh-tools should work |
| Node.js | ≥ 18 (global fetch) |
| Kimi WebBridge daemon | v1.11.5 (tested) |
| Kimi WebBridge browser extension | 1.11.5 (tested) |
| OS | Windows (tested); macOS/Linux supported by code paths, not yet verified |
Compatibility is pinned to what was actually verified. Run node tests/smoke.mjs after installing to check your environment.
📦 Installation
Option A — from GitHub (recommended):
dsh plugin --profile demo add github:MicroHEROX/dsh-Kimi-WebBridge
dsh --profile demo web
Option B — from a local checkout:
dsh plugin --profile demo add ./dsh-Kimi-WebBridge
dsh --profile demo web
Option C — no install, one-off overlay (kimi-webbridge.overlay.yml):
- insert:
- id: kimi-webbridge
name: '/absolute/path/to/dsh-Kimi-WebBridge/index.js'
config:
session: dsh
dsh web --patch ./kimi-webbridge.overlay.yml
Option D — permanent merge: copy the insert block from cordis.patch.yml into $DSH_HOME/profiles/<name>/cordis.patch.yml (or $DSH_HOME/cordis.patch.yml for all profiles).
Uninstall:
dsh plugin --profile demo remove dsh-kimi-webbridge
The CLI removes the dependency and reconciles the profile's layer list; the 15 tools unregister. Verify the row is gone:
dsh --profile demo --dump-config # the kimi-webbridge row must not appear
⚠️ Known harness caveat (dsh 0.1.0-rc.8, discussion #913): on rare transient pnpm failures the entry can remain in dsh.profile.bundles, and the profile then fails to boot with cannot resolve profile bundle "dsh-kimi-webbridge" — dsh plugin install does not fix it (community analysis: #917). Recovery: edit the profile's package.json and delete "dsh-kimi-webbridge" from dsh.profile.bundles, then boot again.
Only runtime files (index.js, cordis.patch.yml, READMEs, LICENSE) are installed; docs/ and tests/ stay in this repository. Verified with npm pack.
🚀 Quick start
- Install the bundle and start
dsh web --profile demo.
- Wait for the
kimi_webbridge_* tools in the catalog.
- Ask: "Open example.com in the browser, tell me what's on the page, and screenshot it."
- The agent opens a tab group (named in your language), reads the page via
snapshot, saves the screenshot, and shows you the file.
⚙️ Configuration
All keys optional; override the kimi-webbridge row from a later patch layer, restating every key you need:
- id: kimi-webbridge
name: dsh-kimi-webbridge
config:
baseUrl: 'http://127.0.0.1:10086' # daemon endpoint
session: dsh # daemon-side tab-group name (one per profile)
requestTimeoutMs: 120000 # per-request timeout
startDaemonTool: true # expose kimi_webbridge_start_daemon
daemonBin: null # override the auto-detected daemon binary
maxRenderText: 50000 # cap on rendered result text
✅ Done / ⚠️ Not done
Done and verified
- All 15 tools end-to-end tested through the real harness + real browser (dsh 0.1.0-rc.8, daemon v1.11.5): navigation, clicking through to real sites, form fill + value verification, file upload +
files.length verification, network capture, CDP layout metrics, screenshots, PDFs, tab management, daemon self-start.
- Automatic retry for capture tools (a fresh tab's first screenshot can stall while the page settles — a retry returns instantly).
- Graceful daemon-unreachable errors with a self-heal path (
kimi_webbridge_start_daemon), tested against a dead port via --patch.
- Schema strictness verified against the real
@deepseek-ai/dsh-tools compile + raw-JSON-schema boundary checks (tests/smoke.mjs).
Not done / known limits
fill/click are ignored by sites that strictly check event.isTrusted (banking portals, captchas) — those need manual interaction. Trusted input is possible at the protocol level via cdp, but that is advanced.- Cross-origin iframes are out of scope:
snapshot/click/fill/evaluate operate on the top frame only.
session is per-profile, not per-agent: subagents share the same tab group. Per-agent session isolation is a future idea (see below).- No
status/health tool yet (the daemon exposes GET /status, but there is no tool for it — a good first contribution).
- macOS/Linux code paths exist but were not verified on real machines.
- CDP is limited to what the extension exposes (browser-level domains such as
Browser.* are not available).
🗺️ Roadmap — routes that work and routes that don't
Viable routes
- ✅ Direct HTTP to the daemon (this plugin) — the only interface WebBridge exposes today.
- ✅ Per-profile session naming; config-driven tool toggles (
startDaemonTool).
- 🔜 Health/status tool over
GET /status; per-agent session mapping; config-driven enable/disable of individual tools.
- 🔜 Publishing to npm once the harness API is stable.
Dead ends (don't go here)
- ❌ Mounting via
@deepseek-ai/dsh-mcp-client — WebBridge has no MCP endpoint (/mcp and /sse return 404; only /command and /status exist). The MCP route used by e.g. Exa does not apply.
- ❌ OAuth login flows (
mcp.exa.ai?login-style) — not supported by the daemon bridge; API keys are not a WebBridge concept either.
- ❌ Daemon lifecycle beyond
start — the plugin never runs stop/restart/uninstall; that is always the user's call.
- ❌ Headless / VM automation — the model acts as you, in your browser; this is not a scraping or CI tool.
🔐 Security
- The daemon listens on
127.0.0.1 only; the model operates your browser as you. Review what your harness is allowed to ask for.
- The plugin stores and sends no credentials, has no filesystem access, and never modifies the
deepseek-harness installation.
kimi_webbridge_cdp and kimi_webbridge_evaluate are powerful; disable them for untrusted model policies.
🧪 Verifying your install
node tests/smoke.mjs
Offline registration + schema-boundary checks always run; live daemon round-trips (navigate → snapshot → evaluate → screenshot → close) run when the daemon is reachable.
🙏 Credits & thanks
- DeepSeek — for the DeepSeek Harness agent runtime and its plugin architecture (
dsh, Cordis, dsh-tools).
- Moonshot AI — for Kimi WebBridge, the local browser bridge this plugin drives.
- The Koishi/Cordis ecosystem — for the plugin framework (
cordis, schemastery) that DeepSeek Harness is built on, and whose conventions this plugin follows.
📌 Version & compatibility
- Plugin: 0.1.0
- Tested with: dsh 0.1.0-rc.8 · Node 24 (≥18 required) · Kimi WebBridge daemon v1.11.5 / extension 1.11.5 · Windows
- Dependencies: none declared —
@deepseek-ai/dsh-tools resolves at runtime from the harness installation (no registry copies are installed)
📚 More docs
📄 License
MIT. Not an official DeepSeek or Moonshot product. WebBridge is a product of Moonshot AI.
