AgentSurf
Let local (stdio) and remote (Streamable HTTP + OAuth 2.0) AI agents control the signed-in Chrome/Edge browser you already have open, with multi-PC window routing and read-only remote defaults.
Dokumentasi
AgentSurf
English | 简体中文
Give any AI agent — local or cloud — safe control over the Chrome or Edge browser you are already signed into.
AgentSurf connects Claude Desktop, Cursor, Codex, Gemini Web, Notion AI, Dify, and any MCP-compatible agent to your real desktop browser. It reuses your existing logins and open tabs without launching headless browsers, exporting cookies, or triggering bot-detection walls.

Why AgentSurf?
If you are choosing between Playwright / Puppeteer MCP, local shell browser skills like Tencent BrowserSkill (bsk), and AgentSurf, here is why users pick AgentSurf:
- Works with Cloud & Web AI — Not Just Local Terminals: Local CLI skills (like
BrowserSkill) require an agent with local bash/shell access, and Playwright MCP launches isolated local sandboxes. AgentSurf exposes standard MCP (stdio+Streamable HTTP) with built-in OAuth 2.0 (PKCE) so Gemini Web, Notion AI, Dify, and mobile/cloud workflows can drive your real desktop browser with zero local shell permission required. - Home + Office Multi-PC on One Gateway: Instead of one daemon bound to one machine, both your home and office browsers connect to the same
wss://.../wsendpoint without kicking each other offline—automatically routing to whichever Chrome window you are actively using. - No Shell Execution Risk & Built for Token Efficiency: Unlike CLI-driven browser skills, your agent never needs shell access to control the browser. Interactive snapshots are filtered and capped inside the page before crossing the wire—on a reference 665-element app page (245 KB raw JSON), the default 150-element cap cuts output from ~66,800 to ~15,100 tokens, and filtering hidden UI (
visible_only: true) or querying bytag/role/name_containsshrinks it further depending on visible page density. - Self-Hosted Privacy & Zero Lock-In: No third-party cloud relay, no telemetry, and no account required. Run 100% offline locally or self-host the single-file
standalone-gateway.js(read-onlyby default on remote, hashed tokens, SHA-256 operation idempotency journal, and zeroMAIN-worldconsolepatching).
| Capability | AgentSurf | Local Shell Browser Skills (e.g. Tencent BrowserSkill) | Headless MCP (Playwright / Puppeteer) |
|---|---|---|---|
| Reuses signed-in Chrome / Edge | Yes (live tabs & cookies) | Yes (live browser via extension) | No (starts fresh or needs brittle profile copies) |
| Anti-bot friendliness | Real desktop browser session | Real desktop browser session | Often flagged by headless automation signals |
| Agent protocol | Standard MCP (stdio + Streamable HTTP) — no shell required | Local CLI (bsk) — requires shell-capable coding agent | Local stdio / local server MCP |
| Cloud Web Agents (Gemini Web, Notion AI, Dify) | Built-in OAuth 2.0 (PKCE) + Bearer + Reverse WSS | Local shell agents only | Local only unless custom-wrapped |
| Home + Office multi-PC routing | Yes — active-window auto-routing, session stickiness & pinning | Single local machine daemon | Single local process |
| Context & token footprint | In-page filtering (visible_only, tag, role, name_contains) + 150-element cap | Page extraction via CLI commands | Large raw DOM / AX tree dumps |
| Safety & isolation | Remote read-only default, per-session Tab Groups, operation_unknown idempotency, zero MAIN-world patching | Dedicated agent window / tab borrowing + human confirmation | Shared browser state; full read/write by default |
Key Features
- Dual-Channel Transport:
- Local Native (
stdio): Zero network dependencies, ultra-low latency via Chrome Native Messaging + loopback bridge (127.0.0.1:8765). - Cloud Remote Gateway (
Streamable HTTP+Reverse WSS): Deploy a single self-containedstandalone-gateway.json any VPS. Your local browser initiates an outbound encrypted WebSocket connection—no port forwarding, SSH tunnels, or public IP needed on your PC.
- Local Native (
- Full OAuth 2.0 + PKCE & Bearer Token Support:
- Implements MCP OAuth discovery (
/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server),Client ID/Client Secret,S256PKCE, consent UI, and refresh tokens—ready for Gemini Web. - Also supports static Bearer Token headers for Notion AI, Dify, and custom HTTP MCP agents.
- Implements MCP OAuth discovery (
- Port-Agnostic Public Routing:
- Host, Origin, and OAuth metadata adapt dynamically to the incoming request
HostandX-Forwarded-Proto, so one gateway config works across standard port443or any alternate reverse-proxy port.
- Host, Origin, and OAuth metadata adapt dynamically to the incoming request
- Multi-Computer Coexistence (Home + Office):
- Connect multiple computers (e.g.,
HomeandOffice) to the samewss://.../wsendpoint without kicking each other offline. - Routes automatically to whichever Chrome window you actively focused/used most recently, locks active sessions to their originating computer, and supports pinning in the extension popup or explicit
devicetargeting.
- Connect multiple computers (e.g.,
- 29 Browser Control Tools (Token-Efficient by Design):
- Semantic interactive element snapshots (
browser_get_interactiveswith opaqueelement_ids, in-page filtering bytag/role/name_contains/visible_only, and default150cap—trimming a 245 KB / 665-element raw snapshot to 150 elements by default, and much smaller when scoped to visible or matching controls). - Page content extraction, click/double-click/type/press/select/checkbox/drag/scroll, viewport & full-page screenshots, iframe navigation, JS dialog handling, downloads, and file uploads (
DOM.setFileInputFiles).
- Semantic interactive element snapshots (
Architecture
flowchart LR
subgraph Local["Local Mode (Zero Network)"]
LAgent["Claude Desktop / Cursor / Codex"] -->|stdio MCP| LServer["agentsurf-mcp"]
LServer -->|Local WS| NHost["Native Messaging Host"]
NHost -->|Native Messaging| Ext["AgentSurf Extension (Chrome / Edge)"]
end
subgraph Cloud["Cloud Mode (OAuth 2.0 + Reverse WSS)"]
CAgent["Gemini Web (OAuth 2.0) / Notion AI / Dify"] -->|HTTPS Streamable MCP| Proxy["Caddy / Nginx HTTPS"]
Proxy --> GW["standalone-gateway.js (:8767)"]
HomeExt["Home Chrome Extension"] -->|Outbound WSS| GW
WorkExt["Office Chrome Extension"] -->|Outbound WSS| GW
end
Quick Start
Prerequisites
| Requirement | Version & Check |
|---|---|
| Node.js | 20+ (node -v) |
| Git | git --version |
| Chrome or Edge | 116+ (chrome://version / edge://version) |
No administrator privileges required. Your existing browser profiles, passwords, and settings are never modified.
Path A: Local Deployment (Claude Desktop, Cursor, Codex, etc.)
-
Clone and run the setup wizard:
git clone https://github.com/ztao0916/agentsurf-browser-control-runtime.git cd agentsurf-browser-control-runtime npm run setupTo configure both Chrome and Edge simultaneously (with separate ports and configs):
npm run setup -- --browser all -
Load the extension in Chrome / Edge:
- Open
chrome://extensions(oredge://extensions) and enable Developer mode. - Click Load unpacked and select the project's
dist/folder. - Copy the generated Extension ID from the AgentSurf card and paste it into the terminal prompt.

- Open
-
Reload & verify the extension popup:
- Click Reload on the AgentSurf extension card, then click the AgentSurf toolbar icon and verify Local Native is active.

-
Add the printed MCP config to your agent:
{ "mcpServers": { "agentsurf": { "command": "<absolute launcher path printed by setup>" } } }When installed with
--browser all,setupprints separateagentsurf-chromeandagentsurf-edgeentries so you can target either browser cleanly.
Path B: Remote Cloud Gateway (Gemini Web, Notion AI, Dify, Remote Agents)
Use Remote Gateway mode when your AI runs in the cloud and needs to control your local browser over HTTPS/WSS.
- Build the single-file gateway locally (
npm run buildproducesdist/mcp/standalone-gateway.jswith zeronode_modulesneeded on the server). - Upload
dist/mcp/standalone-gateway.jsto your server behind Caddy/Nginx HTTPS, initialize credentials (init-remote --url https://mcp.example.com), and start it with PM2 (start-remote). - Pair your Chrome/Edge extension in the popup under Remote Gateway using your
wss://.../wsURL, Pairing Token, and an optional Device Name (e.g.,Home/Office). - Connect your cloud client:
- Gemini Web: Use the generated
OAuth Client IDandOAuth Client Secret, register Gemini's Redirect URI withadd-oauth-redirect --uri "...", and approve the browser prompt with your Pairing Token. - Notion AI / Dify / Custom HTTP MCP: Use
https://mcp.example.com/mcpwithAuthorization: Bearer <token>.
- Gemini Web: Use the generated

Note on Gemini Web confirmations: The demo GIF above trims out waiting spinners and permission cards for brevity. AgentSurf marks read-only inspection tools with MCP
readOnlyHint: true(which Gemini groups under Read and allows automatically), while Gemini Web's client-side security policy still prompts you to clickAlways allowon interactive / state-changing tools (browser_start_session,browser_open,browser_type,browser_click,browser_scroll,browser_end_session, etc.)—even if Write / delete is already set toAlways allowin App actions.
👉 Full step-by-step instructions: Remote Gateway & OAuth 2.0 Guide (docs/remote-gateway.en.md)
Multi-Browser & Multi-Computer Routing
Multiple browsers on one PC (Chrome + Edge)
Each MCP server entry (agentsurf / agentsurf-chrome vs agentsurf-edge) runs its own isolated bridge, tab leases, and sessions. Do not pass a Chrome tab_id or element_id to the Edge server.
Multiple PCs on one Cloud Gateway (Home + Office)
- Connect both browsers to the same
wss://mcp.example.com/wsURL with the same Pairing Token and distinct Device Names (e.g.,Home,Office). - Automatic active routing: The gateway defaults to whichever computer's Chrome window was most recently focused or used by you—idle/background browsers reconnecting will not steal control.
- Session stickiness: Once
browser_start_sessionstarts on a computer, every step of that task stays pinned to that same computer until completion. - Manual control when needed: Click Pin as active in the extension popup to lock a browser, pass
device: "Office"tobrowser_start_session, or connect viahttps://mcp.example.com/mcp?device=Home.
Use and verify
Ask your connected agent:
Open https://example.com and tell me the page title.
Seeing "Chrome is being debugged" during screenshots or file uploads is normal Chrome CDP behavior.
Safety Recommendations
- Start in
read-onlymode when deploying the remote gateway (init-remotedefaults toread-only; explicitly switch tointeractiveonly when ready). - Keep human confirmation before consequential actions such as submitting forms, making purchases, deleting records, uploading files, or sending messages.
- Never share secrets (passwords, OTPs, cookies, or pairing tokens) inside prompts, and never commit local
config.jsonorremote-config.jsonfiles.
Documentation & Links
- Remote Gateway Deployment & OAuth 2.0 Guide (中文版)
- Developer & Protocol Reference (中文版)
- Security Policy
- Contributing
- Changelog
Licensed under the Apache License 2.0.