Skip to content
Back to search

openbrowser-ai

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/billy-enrizky--openbrowser-ai/badge.svg)](/listings/billy-enrizky--openbrowser-ai)

HTML

<a href="/listings/billy-enrizky--openbrowser-ai"><img src="/api/listings/billy-enrizky--openbrowser-ai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Quick install (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

Quick install (Windows PowerShell)

irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Detects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.

Install to `~/.local/bin` without sudo:

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local

Homebrew (macOS / Linux)

brew tap billy-enrizky/openbrowser
brew install openbrowser-ai

pip

pip install openbrowser-ai

uv (recommended)

uv pip install openbrowser-ai

uvx (zero install)

Run directly without installing -- `uvx` downloads and caches the package automatically:

# MCP server mode
uvx openbrowser-ai --mcp

# CLI daemon mode
uvx openbrowser-ai -c "await navigate('https://example.com')"

pipx

pipx install openbrowser-ai

From source

git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser-ai
uv pip install -e ".[agent]"

Optional Dependencies

pip install openbrowser-ai[agent]      # LLM agent support (langgraph, langchain, litellm)
pip install openbrowser-ai[all]        # All LLM providers
pip install openbrowser-ai[anthropic]  # Anthropic Claude
pip install openbrowser-ai[groq]       # Groq
pip install openbrowser-ai[ollama]     # Ollama (local models)
pip install openbrowser-ai[aws]        # AWS Bedrock
pip install openbrowser-ai[azure]      # Azure OpenAI
pip install openbrowser-ai[video]      # Video recording support

> **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines
  1. {
  2. "name": "openbrowser-ai",
  3. "owner": {
  4. "name": "OpenBrowser Team",
  5. "email": "billy.enrizky@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "AI-powered browser automation for Claude Code -- navigate, click, type, extract content, and automate workflows in real browsers. Supports MCP server and CLI daemon modes."
  9. },
  10. "plugins": [
  11. {
  12. "name": "openbrowser",
  13. "version": "0.1.56",
  14. "description": "Browser automation MCP server with progressive disclosure design -- uses 3.2x fewer tokens than Playwright MCP across 6 tasks. Single execute_code tool runs Python with async browser functions, persisted login sessions, CLI daemon workflows, and compact description mode for token optimization.",
  15. "source": "./plugin",
  16. "category": "development",
  17. "tags": [
  18. "browser",
  19. "automation",
  20. "web-scraping",
  21. "mcp",
  22. "testing",
  23. "cli",
  24. "daemon"
  25. ],
  26. "homepage": "https://github.com/billy-enrizky/openbrowser-ai",
  27. "repository": "https://github.com/billy-enrizky/openbrowser-ai",
  28. "license": "MIT"
  29. }
  30. ]
  31. }
README.md · README · 815 lines · 3 findings marked
  1. <p align="center">
  2. <img src="docs/logo/icon.svg" alt="OpenBrowser" width="120" height="120" />
  3. </p>
  4. <h1 align="center">OpenBrowser</h1>
  5. <p align="center"><strong>AI browser automation, powered by code.</strong></p>
  6. ---
  7. **Cloud dashboard for saved cookies and scheduled tasks is available in the hosted version. Join the waitlist for early access: https://openbrowser.me** :
  8. https://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b
  9. **Automating Walmart Product Scraping:**
  10. https://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094
  11. **OpenBrowserAI Automatic Flight Booking:**
  12. https://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f
  13. **OpenBrowserAI Automatic Form Filling:**
  14. https://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7
  15. [![PyPI version](https://badge.fury.io/py/openbrowser-ai.svg)](https://pypi.org/project/openbrowser-ai/)
  16. [![Downloads](https://img.shields.io/pypi/dm/openbrowser-ai?color=brightgreen&label=downloads)](https://pepy.tech/projects/openbrowser-ai)
  17. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  18. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  19. [![Tests](https://github.com/billy-enrizky/openbrowser-ai/actions/workflows/test.yml/badge.svg)](https://github.com/billy-enrizky/openbrowser-ai/actions)
  20. [![Coverage](https://codecov.io/gh/billy-enrizky/openbrowser-ai/branch/main/graph/badge.svg)](https://codecov.io/gh/billy-enrizky/openbrowser-ai)
  21. <!-- mcp-name: me.openbrowser/openbrowser-ai -->
  22. **AI-powered browser automation using CodeAgent and CDP (Chrome DevTools Protocol)**
  23. OpenBrowser is a framework for intelligent browser automation. It combines direct CDP communication with a CodeAgent architecture, where the LLM writes Python code executed in a persistent namespace, to navigate, interact with, and extract information from web pages autonomously.
  24. ## Table of Contents
  25. - [Documentation](#documentation)
  26. - [Key Features](#key-features)
  27. - [Installation](#installation)
  28. - [Quick Start](#quick-start)
  29. - [Configuration](#configuration)
  30. - [Supported LLM Providers](#supported-llm-providers)
  31. - [Claude Code Plugin](#claude-code-plugin)
  32. - [Codex](#codex)
  33. - [OpenCode](#opencode)
  34. - [OpenClaw](#openclaw)
  35. - [MCP Server](#mcp-server)
  36. - [Benchmark: Token Efficiency](#benchmark-token-efficiency)
  37. - [CLI Usage](#cli-usage)
  38. - [Project Structure](#project-structure)
  39. - [Backend and Frontend Deployment](#backend-and-frontend-deployment)
  40. - [Testing](#testing)
  41. - [Research: Reinforcement Fine-Tuning for Browser Agents](#research-reinforcement-fine-tuning-for-browser-agents)
  42. - [Contributing](#contributing)
  43. - [License](#license)
  44. - [Contact](#contact)
  45. ## Documentation
  46. **Full documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)
  47. ## Key Features
  48. - **CodeAgent Architecture** - LLM writes Python code in a persistent Jupyter-like namespace for browser automation
  49. - **Raw CDP Communication** - Direct Chrome DevTools Protocol for maximum control and speed
  50. - **Vision Support** - Screenshot analysis for visual understanding of pages
  51. - **15 LLM Providers** - OpenAI, Anthropic, Google, Groq, AWS Bedrock, Azure, Ollama, DeepSeek, Cerebras, OpenRouter, OCI, and more
  52. - **MCP Server** - Model Context Protocol for Claude Desktop, Claude Code, Codex, OpenCode, and other AI assistants, with reusable saved login sessions
  53. - **CLI Daemon** - Persistent browser daemon with `-c` flag for direct code execution from Bash, saved login state, and 10-minute auto-shutdown
  54. - **Workflow Recording** - Record, replay, and export browser sessions to Jupyter notebooks or API crawler code
  55. - **Video Recording** - Record browser sessions as video files with ffmpeg
  56. - **Cloud Platform** - Full-stack web UI with real-time VNC streaming, saved logins (KMS-encrypted), scheduled workflows (EventBridge + SQS), and email notifications (SES)
  57. - **Plugin System** - Claude Code plugin with 7 guided skills (deep research, web scraping, form filling, e2e testing, page analysis, accessibility audit, file download)
  58. ## Installation
  59. ### Quick install (macOS / Linux)
  60. ```bash
  61. curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 86 on GitHub
  62. ```
  63. ### Quick install (Windows PowerShell)
  64. ```powershell
  65. irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex
  66. ```
  67. Detects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.
  68. Install to `~/.local/bin` without sudo:
  69. ```bash
  70. curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 100 on GitHub
  71. ```
  72. ### Homebrew (macOS / Linux)
  73. ```bash
  74. brew tap billy-enrizky/openbrowser
  75. brew install openbrowser-ai
  76. ```
  77. ### pip
  78. ```bash
  79. pip install openbrowser-ai
  80. ```
  81. ### uv (recommended)
  82. ```bash
  83. uv pip install openbrowser-ai
  84. ```
  85. ### uvx (zero install)
  86. Run directly without installing -- `uvx` downloads and caches the package automatically:
  87. ```bash
  88. # MCP server mode
  89. uvx openbrowser-ai --mcp
  90. # CLI daemon mode
  91. uvx openbrowser-ai -c "await navigate('https://example.com')"
  92. ```
  93. ### pipx
  94. ```bash
  95. pipx install openbrowser-ai
  96. ```
  97. ### From source
  98. ```bash
  99. git clone https://github.com/billy-enrizky/openbrowser-ai.git
  100. cd openbrowser-ai
  101. uv pip install -e ".[agent]"
  102. ```
  103. ### Optional Dependencies
  104. ```bash
  105. pip install openbrowser-ai[agent] # LLM agent support (langgraph, langchain, litellm)
  106. pip install openbrowser-ai[all] # All LLM providers
  107. pip install openbrowser-ai[anthropic] # Anthropic Claude
  108. pip install openbrowser-ai[groq] # Groq
  109. pip install openbrowser-ai[ollama] # Ollama (local models)
  110. pip install openbrowser-ai[aws] # AWS Bedrock
  111. pip install openbrowser-ai[azure] # Azure OpenAI
  112. pip install openbrowser-ai[video] # Video recording support
  113. ```
  114. > **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`
  115. ## Quick Start
  116. ### Basic Usage
  117. ```python
  118. import asyncio
  119. from openbrowser import CodeAgent, ChatGoogle
  120. async def main():
  121. agent = CodeAgent(
  122. task="Go to google.com and search for 'Python tutorials'",
  123. llm=ChatGoogle(model="gemini-3-flash"),
  124. )
  125. result = await agent.run()
  126. print(f"Result: {result}")
  127. asyncio.run(main())
  128. ```
  129. ### With Different LLM Providers
  130. ```python
  131. from openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle
  132. # OpenAI
  133. agent = CodeAgent(task="...", llm=ChatOpenAI(model="gpt-5.2"))
  134. # Anthropic
  135. agent = CodeAgent(task="...", llm=ChatAnthropic(model="claude-sonnet-4-6"))
  136. # Google Gemini
  137. agent = CodeAgent(task="...", llm=ChatGoogle(model="gemini-3-flash"))
  138. ```
  139. ### Using Browser Session Directly
  140. ```python
  141. import asyncio
  142. from openbrowser import BrowserSession, BrowserProfile
  143. async def main():
  144. profile = BrowserProfile(
  145. headless=True,
  146. viewport={"width": 1920, "height": 1080},
  147. )
  148. session = BrowserSession(browser_profile=profile)
  149. await session.start()
  150. await session.navigate_to("https://example.com")
  151. screenshot = await session.screenshot()
  152. await session.stop()
  153. asyncio.run(main())
  154. ```
  155. `await session.navigate_to(url)` waits for the document's `load` milestone, not a fixed delay. Use keyword options such as `wait_until="domcontentloaded"` and `timeout_ms=10000` to choose another milestone and deadline. Supported milestones are `commit`, `domcontentloaded`, `load`, and Chromium's `networkIdle` lifecycle event through `wait_until="networkidle"`. They do not establish application hydration or business-task completion.
  156. Cancelling `navigate_to()` cancels that request without replaying navigation. An overlapping request raises `NavigationBusyError`; wait for the active request to finish before trying again. A download handoff still returns `None`, but is recorded as `download`, not document readiness. `session.lifecycle_snapshot()["navigation"]` reports the active or last operation, including its requested URL, observed URL, generation, phase, and error.
  157. ## Configuration
  158. ### Environment Variables
  159. ```bash
  160. # Google (recommended)
  161. export GOOGLE_API_KEY="..."
  162. # OpenAI
  163. export OPENAI_API_KEY="sk-..."
  164. # Anthropic
  165. export ANTHROPIC_API_KEY="sk-ant-..."
  166. # Groq
  167. export GROQ_API_KEY="gsk_..."
  168. # AWS Bedrock
  169. export AWS_ACCESS_KEY_ID="..."
  170. export AWS_SECRET_ACCESS_KEY="..."
  171. export AWS_DEFAULT_REGION="us-west-2"
  172. # Azure OpenAI
  173. export AZURE_OPENAI_API_KEY="..."
  174. export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
  175. ```
  176. ### BrowserProfile Options
  177. ```python
  178. from openbrowser import BrowserProfile
  179. profile = BrowserProfile(
  180. headless=True,
  181. viewport={"width": 1280, "height": 720},
  182. disable_security=False,
  183. extra_chromium_args=["--disable-gpu"],
  184. record_video_dir="./recordings",
  185. proxy={
  186. "server": "http://proxy.example.com:8080",
  187. "username": "user",
  188. "password": "pass",
  189. },
  190. )
  191. ```
  192. ## Supported LLM Providers
  193. | Provider | Class | Models |
  194. |----------|-------|--------|
  195. | **Google** | `ChatGoogle` | gemini-3-flash, gemini-3-pro |
  196. | **OpenAI** | `ChatOpenAI` | gpt-5.2, o4-mini, o3 |
  197. | **Anthropic** | `ChatAnthropic` | claude-sonnet-4-6, claude-opus-4-6 |
  198. | **Groq** | `ChatGroq` | llama-4-scout, qwen3-32b |
  199. | **AWS Bedrock** | `ChatAWSBedrock` | anthropic.claude-sonnet-4-6, amazon.nova-pro |
  200. | **AWS Bedrock (Anthropic)** | `ChatAnthropicBedrock` | Claude models via Anthropic Bedrock SDK |
  201. | **Azure OpenAI** | `ChatAzureOpenAI` | Any Azure-deployed model |
  202. | **OpenRouter** | `ChatOpenRouter` | Any model on openrouter.ai |
  203. | **DeepSeek** | `ChatDeepSeek` | deepseek-chat, deepseek-r1 |
  204. | **Cerebras** | `ChatCerebras` | llama-4-scout, qwen-3-235b |
  205. | **Ollama** | `ChatOllama` | llama-4-scout, deepseek-r1 (local) |
  206. | **OCI** | `ChatOCIRaw` | Oracle Cloud GenAI models |
  207. | **Browser-Use** | `ChatBrowserUse` | External LLM service |
  208. ## Claude Code Plugin
  209. Install OpenBrowser as a Claude Code plugin:
  210. ```bash
  211. # Add the marketplace (one-time)
  212. claude plugin marketplace add billy-enrizky/openbrowser-ai
  213. # Install the plugin
  214. claude plugin install openbrowser@openbrowser-ai
  215. ```
  216. This installs the MCP server and 7 built-in skills:
  217. | Skill | Description |
  218. |-------|-------------|
  219. | `deep-research` | Conduct cited, multi-source web research and produce markdown and JSON reports |
  220. | `web-scraping` | Extract structured data, handle pagination |
  221. | `form-filling` | Fill forms, login flows, multi-step wizards |
  222. | `e2e-testing` | Test web apps by simulating user interactions |
  223. | `page-analysis` | Analyze page content, structure, metadata |
  224. | `accessibility-audit` | Audit pages for WCAG compliance |
  225. | `file-download` | Download files (PDFs, CSVs) using browser session |
  226. See [plugin/README.md](plugin/README.md) for detailed tool parameter documentation.
  227. ## Codex
  228. OpenBrowser works with OpenAI Codex via native skill discovery.
  229. ### Quick Install
  230. Tell Codex:
  231. ```
  232. Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md
  233. ```
  234. ### Manual Install
  235. ```bash
  236. # Clone the repository
  237. git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser
  238. # Symlink skills for native discovery
  239. mkdir -p ~/.agents/skills
  240. ln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser
  241. # Restart Codex
  242. ```
  243. Then configure the MCP server in your project (see [MCP Server](#mcp-server) below).
  244. Detailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)
  245. ## OpenCode
  246. OpenBrowser works with [OpenCode.ai](https://opencode.ai) via plugin and skill symlinks.
  247. ### Quick Install
  248. Tell OpenCode:
  249. ```
  250. Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md
  251. ```
  252. ### Manual Install
  253. ```bash
  254. # Clone the repository
  255. git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser
  256. # Create directories
  257. mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
  258. # Symlink plugin and skills
  259. ln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js
  260. ln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser
  261. # Restart OpenCode
  262. ```
  263. Then configure the MCP server in your project (see [MCP Server](#mcp-server) below).
  264. Detailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)
  265. ## OpenClaw
  266. [OpenClaw](https://openclaw.ai) supports OpenBrowser via the CLI daemon. Install OpenBrowser,
  267. then use `openbrowser-ai -c` from the Bash tool:
  268. ```bash
  269. openbrowser-ai -c "await navigate('https://example.com')"
  270. openbrowser-ai -c "print(await evaluate('document.title'))"
  271. ```
  272. The daemon starts automatically on first use and persists variables across calls.
  273. For OpenClaw plugin documentation, see [docs.openclaw.ai/tools/plugin](https://docs.openclaw.ai/tools/plugin).
  274. ## MCP Server
  275. [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/?q=openbrowser)
  276. OpenBrowser includes an MCP (Model Context Protocol) server that exposes browser automation as tools for AI assistants like Claude. Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?q=openbrowser) as `me.openbrowser/openbrowser-ai`. No external LLM API keys required -- the MCP client provides the intelligence.
  277. By default, each MCP server process uses an isolated profile under `~/.config/openbrowser/profiles/mcp-<instance-id>`. Its `storage_state.json` is seeded once from `~/.config/openbrowser/profiles/default/storage_state.json`, so existing logins are available without allowing concurrent MCP servers to kill or corrupt one another's browser. The per-process profile is retained on disk but is not automatically reused by a later MCP process. Configure `OPENBROWSER_USER_DATA_DIR` for a profile that survives restarts; `OPENBROWSER_STORAGE_STATE` is a one-time seed for managed profiles, and later changes are saved to the active per-process copy rather than copied back automatically. OpenBrowser also auto-cleans disposable Chromium caches in managed profiles, which keeps disk usage down without deleting cookies or login state. If you explicitly configure the same `OPENBROWSER_USER_DATA_DIR` for multiple servers, the profile lease rejects the second owner with a clear error.
  278. ### Quick Setup
  279. **Claude Code**: add to your project's `.mcp.json`:
  280. ```json
  281. {
  282. "mcpServers": {
  283. "openbrowser": {
  284. "command": "uvx",
  285. "args": ["openbrowser-ai", "--mcp"]
  286. }
  287. }
  288. }
  289. ```
  290. **Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  291. ```json
  292. {
  293. "mcpServers": {
  294. "openbrowser": {
  295. "command": "uvx",
  296. "args": ["openbrowser-ai", "--mcp"],
  297. "env": {
  298. "OPENBROWSER_HEADLESS": "true"
  299. }
  300. }
  301. }
  302. }
  303. ```
  304. **Run directly:**
  305. ```bash
  306. uvx openbrowser-ai --mcp
  307. ```
  308. ### Tools
  309. The MCP server exposes three tools:
  310. - `execute_code` runs Python code in a persistent namespace with browser automation functions.
  311. - `get_status` returns server, browser, profile, and tab state as JSON. It is read-only and does not start a browser.
  312. - `reset_browser` closes a stuck browser and preserves user-defined Python variables unless `clear_variables` is true.
  313. If a browser connection fails, call `get_status` before retrying. Do not replay a page-changing action blindly because the first attempt may have partially run.
  314. **Available functions** (use `await` unless noted):
  315. | Category | Functions |
  316. |----------|-----------|
  317. | **Navigation** | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)` |
  318. | **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |
  319. | **Coordinate interaction** | `click_xy(x, y, button, click_count)`, `hover_xy(x, y)`, `scroll_xy(x, y, delta_x, delta_y)` for no-index canvas, PDF, embedded, and native-rendered targets |
  320. | **Dropdowns** | `select_dropdown(index, text)`, `dropdown_options(index)` |
  321. | **Tabs** | `switch(tab_id)`, `close(tab_id)`: accepts the four-character suffix or the full CDP target ID |
  322. | **JavaScript** | `evaluate(code)`: run JS in page context, returns Python objects |
  323. | **Downloads** | `download_file(url, filename)`: download a file using browser cookies, `list_downloads()`: list downloaded files (sync, no `await`) |
  324. | **State** | `browser.get_browser_state_summary()`: get page metadata and interactive elements |
  325. | **CSS** | `get_selector_from_index(index)`: get CSS selector for an element |
  326. | **Completion** | `done(text, success)`: signal task completion |
  327. Prefer indexed actions whenever an element index exists. Coordinate actions use CSS viewport pixels, not screenshot pixels. If a screenshot uses a `devicePixelRatio` other than 1, divide its coordinates by `window.devicePixelRatio` before calling an `*_xy` function.
  328. **Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`
  329. ### Configuration
  330. | Environment Variable | Description | Default |
  331. |---------------------|-------------|---------|
  332. | `OPENBROWSER_HEADLESS` | Run browser without GUI | `true` |
  333. | `OPENBROWSER_ALLOWED_DOMAINS` | Comma-separated domain whitelist | (none) |
  334. | `OPENBROWSER_USER_DATA_DIR` | Optional explicit Chrome profile directory. Omit it for an isolated profile per MCP server instance | (auto: `~/.config/openbrowser/profiles/mcp-<instance-id>`) |
  335. | `OPENBROWSER_STORAGE_STATE` | Optional JSON file used as a one-time seed for cookies plus localStorage in managed MCP profiles | (auto: per-process copy, seeded from `profiles/default`) |
  336. | `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (~500 tokens) | `false` |
  337. | `OPENBROWSER_MAX_OUTPUT` | Max output characters per execution | `10000` |
  338. | `OPENBROWSER_MCP_START_TIMEOUT` | Browser startup bound in seconds | `30` |
  339. | `OPENBROWSER_MCP_EXEC_TIMEOUT` | Seconds before a tool call returns a timeout result | `110` |
  340. ## Benchmark: Token Efficiency
  341. The figures below are historical model-driven benchmark results, not a comparison of current tool releases or navigation latency. For a local, no-LLM comparison with pinned runtimes and verified page work, use the [navigation comparison verifier](benchmarks/navigation_compare_README.md), its [counterbalanced policy-fix results](benchmarks/navigation_results_2026-11-15_policy_v2.json), and the retained [earlier results](benchmarks/navigation_results_2026-11-15.json). These report engine, IPC, wait-policy, failure, and cleanup differences rather than declaring a universal winner. They are not MCP or CLI agent-comparison numbers.
  342. ### CLI Benchmark: 4-Way Comparison (6 Tasks, N=3 runs)
  343. Four CLI tools compared with a single Bash tool each. Claude Sonnet 4.6 on Bedrock. Randomized order. All achieve 100% accuracy.
  344. <p align="center">
  345. <img src="benchmarks/cli_benchmark_scatter.png" alt="CLI Benchmark: Token Usage vs Duration" width="800" />
  346. </p>
  347. | CLI Tool | Duration (mean +/- std) | Tool Calls | Bedrock API Tokens | Response Chars |
  348. |----------|------------------------:|-----------:|-------------------:|---------------:|
  349. | **openbrowser-ai** | **84.8 +/- 10.9s** | **15.3 +/- 2.3** | **36,010 +/- 6,063** | **9,452 +/- 472** |
  350. | browser-use | 106.0 +/- 9.5s | 20.7 +/- 6.4 | 77,123 +/- 33,354 | 36,241 +/- 12,940 |
  351. | agent-browser | 99.0 +/- 6.8s | 25.0 +/- 4.0 | 90,107 +/- 3,698 | 56,009 +/- 39,733 |
  352. | playwright-cli | 118.3 +/- 21.4s | 25.7 +/- 8.1 | 94,130 +/- 35,982 | 84,065 +/- 49,713 |
  353. openbrowser-ai uses **2.1-2.6x fewer tokens** than all competitors via Python code batching and compact DOM representation.
  354. <p align="center">
  355. <img src="benchmarks/cli_benchmark_overview.png" alt="CLI Benchmark: Overview" width="800" />
  356. </p>
  357. #### Per-Task Token Usage
  358. <p align="center">
  359. <img src="benchmarks/cli_benchmark_per_task.png" alt="CLI Benchmark: Per-Task Token Usage" width="800" />
  360. </p>
  361. | Task | openbrowser-ai | browser-use | playwright-cli | agent-browser |
  362. |------|---------------:|------------:|---------------:|--------------:|
  363. | fact_lookup | **2,504** | 4,710 | 16,857 | 9,676 |
  364. | form_fill | **7,887** | 15,811 | 31,757 | 19,226 |
  365. | multi_page_extract | **2,354** | 2,405 | 8,886 | 8,117 |
  366. | search_navigate | **16,539** | 47,936 | 27,779 | 44,367 |
  367. | deep_navigation | **2,178** | 3,747 | 4,705 | 5,534 |
  368. | content_analysis | 4,548 | **2,515** | 4,147 | 3,189 |
  369. openbrowser-ai wins 5 of 6 tasks. The advantage is largest on complex pages (search_navigate: 2.9x fewer tokens than browser-use) where code batching avoids repeated page state dumps.
  370. #### Cost per Benchmark Run (6 Tasks)
  371. | Model | openbrowser-ai | browser-use | playwright-cli | agent-browser |
  372. |-------|---------------:|------------:|---------------:|--------------:|
  373. | Claude Sonnet 4.6 ($3/$15 per M) | **$0.12** | $0.24 | $0.29 | $0.27 |
  374. | Claude Opus 4.6 ($5/$25 per M) | **$0.24** | $0.45 | $0.56 | $0.51 |
  375. Raw results are in [`benchmarks/e2e_4way_cli_results.json`](benchmarks/e2e_4way_cli_results.json). [Full 4-way comparison with methodology](https://docs.openbrowser.me/cli-comparison).
  376. ### E2E LLM Benchmark: MCP Server Comparison (6 Tasks, N=5 runs)
  377. <p align="center">
  378. <img src="benchmarks/benchmark_comparison.png" alt="E2E LLM Benchmark: MCP Server Comparison" width="800" />
  379. </p>
  380. | MCP Server | Pass Rate | Duration (mean +/- std) | Tool Calls | Bedrock API Tokens |
  381. |------------|:---------:|------------------------:|-----------:|-------------------:|
  382. | **Playwright MCP** (Microsoft) | 100% | 62.7 +/- 4.8s | 9.4 +/- 0.9 | 158,787 |
  383. | **Chrome DevTools MCP** (Google) | 100% | 103.4 +/- 2.7s | 19.4 +/- 0.5 | 299,486 |
  384. | **OpenBrowser MCP** | 100% | 77.0 +/- 6.7s | 13.8 +/- 2.0 | **50,195** |
  385. OpenBrowser uses **3.2x fewer tokens** than Playwright and **6.0x fewer** than Chrome DevTools. MCP response sizes: Playwright 1,132,173 chars, Chrome DevTools 1,147,244 chars, OpenBrowser 7,853 chars -- a **144x difference**.
  386. [Full MCP comparison with methodology](https://docs.openbrowser.me/comparison)
  387. ## CLI Usage
  388. ```bash
  389. # Run a browser automation task with an LLM agent
  390. uvx openbrowser-ai -p "Search for Python tutorials on Google"
  391. # Execute code directly via persistent daemon
  392. uvx openbrowser-ai -c "await navigate('https://example.com')"
  393. uvx openbrowser-ai -c "print(await evaluate('document.title'))"
  394. # Daemon management
  395. uvx openbrowser-ai daemon ensure # Start or restart a daemon that matches the requested headless and profile settings
  396. uvx openbrowser-ai daemon start # Start daemon (auto-starts on first -c call)
  397. uvx openbrowser-ai daemon stop # Stop daemon and browser
  398. uvx openbrowser-ai daemon force-stop # Force-stop the current endpoint after verifying the owner
  399. uvx openbrowser-ai daemon status # Show lifecycle, profile, browser, and tab state
  400. uvx openbrowser-ai daemon reset # Close the browser but keep the daemon process
  401. uvx openbrowser-ai daemon doctor # Diagnose socket, PID, profile, and log state
  402. uvx openbrowser-ai daemon list # List sockets and this user's daemon processes
  403. uvx openbrowser-ai daemon reap # Stop verified daemons and reap orphaned daemon processes
  404. uvx openbrowser-ai daemon restart # Restart daemon
  405. # Install browser
  406. uvx openbrowser-ai install
  407. # Run MCP server
  408. uvx openbrowser-ai --mcp
  409. ```
  410. The `-c` flag connects to a persistent browser daemon over a Unix socket (localhost TCP on Windows). Variables persist across calls while the daemon is running. The daemon starts automatically on first use and shuts down after 10 minutes of inactivity.
  411. The CLI daemon stores its browser profile in `~/.config/openbrowser/profiles/daemon`, so cookies and login sessions survive daemon restarts through Chrome's user-data directory. An explicit `storage_state` path is still loaded when configured. Custom sockets share the default profile by default to preserve existing logins. Set `OPENBROWSER_DAEMON_PROFILE_ISOLATION=true` or `OPENBROWSER_DAEMON_PROFILE_DIR` when several daemons must run with separate profiles. `OPENBROWSER_USER_DATA_DIR` takes precedence over both and always selects that explicit profile. One-shot `-p` runs use `~/.config/openbrowser/profiles/cli`. Managed profiles automatically clear disposable browser caches on startup and shutdown while keeping auth state.
  412. Execution defaults to 110 seconds so an agent with a 120 second tool timeout receives a structured timeout response. Override it with `OPENBROWSER_EXEC_TIMEOUT` and set `OPENBROWSER_READ_TIMEOUT` above that value if you need longer calls. `OPENBROWSER_DAEMON_INIT_TIMEOUT` and `OPENBROWSER_SHUTDOWN_TIMEOUT` bound browser startup and cleanup.
  413. ## Project Structure
  414. ```
  415. openbrowser-ai/
  416. ├── .claude-plugin/ # Claude Code marketplace config
  417. ├── .codex/ # Codex integration
  418. │ └── INSTALL.md
  419. ├── .opencode/ # OpenCode integration
  420. │ ├── INSTALL.md
  421. │ └── plugins/openbrowser.js
  422. ├── plugin/ # Plugin package (skills + MCP config)
  423. │ ├── .claude-plugin/
  424. │ ├── .mcp.json
  425. │ └── skills/ # 7 browser automation skills
  426. ├── src/openbrowser/
  427. │ ├── __init__.py # Main exports
  428. │ ├── cli.py # CLI commands
  429. │ ├── config.py # Configuration
  430. │ ├── actor/ # Element interaction
  431. │ ├── agent/ # LangGraph agent
  432. │ ├── browser/ # CDP browser control
  433. │ ├── code_use/ # Code agent + shared executor
  434. │ ├── daemon/ # Persistent browser daemon (Unix socket)
  435. │ ├── dom/ # DOM extraction
  436. │ ├── llm/ # LLM providers
  437. │ ├── mcp/ # MCP server
  438. │ └── tools/ # Action registry
  439. ├── benchmarks/ # MCP benchmarks and E2E tests
  440. │ ├── playwright_benchmark.py
  441. │ ├── cdp_benchmark.py
  442. │ ├── openbrowser_benchmark.py
  443. │ └── e2e_published_test.py
  444. └── tests/ # Test suite
  445. ```
  446. ## Testing
  447. ```bash
  448. # Run unit tests
  449. pytest tests/
  450. # Run with verbose output
  451. pytest tests/ -v
  452. # E2E test the MCP server against the published PyPI package
  453. uv run python benchmarks/e2e_published_test.py
  454. ```
  455. ### Benchmarks
  456. Run individual MCP server benchmarks (JSON-RPC stdio, 5-step Wikipedia workflow):
  457. ```bash
  458. uv run python benchmarks/openbrowser_benchmark.py # OpenBrowser MCP
  459. uv run python benchmarks/playwright_benchmark.py # Playwright MCP
  460. uv run python benchmarks/cdp_benchmark.py # Chrome DevTools MCP
  461. ```
  462. Raw results are in [`benchmarks/e2e_4way_cli_results.json`](benchmarks/e2e_4way_cli_results.json). See [full comparison](https://docs.openbrowser.me/comparison) for methodology.
  463. ## Backend and Frontend Deployment
  464. The project includes a FastAPI backend and a Next.js frontend, both containerized with Docker.
  465. ### Prerequisites
  466. - Docker and Docker Compose
  467. - A `.env` file in the project root with `POSTGRES_PASSWORD` and any LLM API keys (see `backend/env.example`)
  468. ### Local Development (Docker Compose)
  469. ```bash
  470. # Start backend + PostgreSQL (frontend runs locally)
  471. docker-compose -f docker-compose.dev.yml up --build
  472. # In a separate terminal, start the frontend
  473. cd frontend && npm install && npm run dev
  474. ```
  475. | Service | URL | Description |
  476. |---------|-----|-------------|
  477. | Backend | http://localhost:8000 | FastAPI + WebSocket + VNC |
  478. | Frontend | http://localhost:3000 | Next.js dev server |
  479. | PostgreSQL | localhost:5432 | Chat persistence |
  480. | VNC | ws://localhost:6080 | Live browser view |
  481. The dev compose mounts `backend/app/` and `src/` as volumes for hot-reload. API keys are loaded from `backend/.env` via `env_file`. The `POSTGRES_PASSWORD` is read from the root `.env` file.
  482. ### Full Stack (Docker Compose)
  483. ```bash
  484. # Start all services (backend + frontend + PostgreSQL)
  485. docker-compose up --build
  486. ```
  487. This builds and runs both the backend and frontend containers together with PostgreSQL.
  488. ### Backend
  489. The backend is a FastAPI application in `backend/` with a Dockerfile at `backend/Dockerfile`. It includes:
  490. - REST API on port 8000
  491. - WebSocket endpoint at `/ws` for real-time agent communication
  492. - VNC support (Xvfb + x11vnc + websockify) for live browser viewing on ports 6080-6090
  493. - Kiosk security: Openbox window manager, Chromium enterprise policies, X11 key grabber daemon
  494. - Health check at `/health`
  495. ```bash
  496. # Build the backend image
  497. docker build -f backend/Dockerfile -t openbrowser-backend .
  498. # Run standalone
  499. docker run -p 8000:8000 -p 6080:6080 \
  500. --env-file backend/.env \
  501. -e VNC_ENABLED=true \
  502. -e AUTH_ENABLED=false \
  503. --shm-size=2g \
  504. openbrowser-backend
  505. ```
  506. ### Frontend
  507. The frontend is a Next.js application in `frontend/` with a Dockerfile at `frontend/Dockerfile`.
  508. ```bash
  509. # Build the frontend image
  510. cd frontend && docker build -t openbrowser-frontend .
  511. # Run standalone
  512. docker run -p 3000:3000 \
  513. -e NEXT_PUBLIC_API_URL=http://localhost:8000 \
  514. -e NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws \
  515. openbrowser-frontend
  516. ```
  517. ### Environment Variables
  518. Key environment variables for the backend (see `backend/env.example` for the full list):
  519. | Variable | Description | Default |
  520. |----------|-------------|---------|
  521. | `GOOGLE_API_KEY` | Google/Gemini API key | (required) |
  522. | `DEFAULT_LLM_MODEL` | Default model for agents | `gemini-3-flash-preview` |
  523. | `AUTH_ENABLED` | Enable Cognito JWT auth | `false` |
  524. | `VNC_ENABLED` | Enable VNC browser viewing | `true` |
  525. | `DATABASE_URL` | PostgreSQL connection string | (optional) |
  526. | `POSTGRES_PASSWORD` | PostgreSQL password (root `.env`) | (required for compose) |
  527. ## Research: Reinforcement Fine-Tuning for Browser Agents
  528. Beyond the framework, we conducted two independent research studies on improving browser agents through reinforcement learning, both using the [FormFactory benchmark](https://arxiv.org/abs/2506.01520) (1,250 form-filling tasks across 8 domains) and OpenBrowser's browser execution environment.
  529. ### Study 1: Browser-in-the-Loop (Autoregressive RL)
  530. We investigated whether reinforcement learning can improve a language model's ability to fill web forms beyond what supervised learning achieves.
  531. - **Method**: Two-phase pipeline -- SFT on Qwen3-8B with QLoRA (992 demonstrations), then online GRPO with live browser execution rewards (composite: 40% submission success + 40% field accuracy + 20% execution completeness)
  532. - **Result**: GRPO achieves 9.1% higher average reward than SFT alone on held-out validation (p=0.007, Wilcoxon signed-rank test). Improvement comes specifically from better form submission, not field filling.
  533. - **Key finding**: SFT is a prerequisite -- without it, the base model generates unstructured text and earns zero reward across all attempts.
  534. - **Paper**: [Browser-in-the-Loop: Reinforcement Fine-Tuning LLM Agents for Web Form Filling](https://www.researchgate.net/profile/Muhammad-Enrizky-Brillian)
  535. - **Models**: [Qwen3-8B-FormFactory-SFT-LoRA](https://huggingface.co/billyenrizky/Qwen3-8B-FormFactory-SFT-LoRA), [Qwen3-8B-FormFactory-GRPO-LoRA](https://huggingface.co/billyenrizky/Qwen3-8B-FormFactory-GRPO-LoRA)
  536. ### Study 2: Diffusion Language Models for Web Action Planning
  537. We investigated whether diffusion language models -- which generate text by iteratively denoising an entire sequence in parallel rather than left-to-right -- can learn web action planning.
  538. - **Models tested**: ReFusion 8B (masked diffusion with causal LM backbone) and FS-DFM 1.3B (pure discrete flow matching)
  539. - **Result**: After SFT, diffusion models solve 60-69% of tasks vs. 100% for the AR baseline. Token-level RL is universally fragile (2/16 comparisons improve, both insignificant). Sequence-level RL succeeds: MDPO pushes ReFusion to 91.9% (+31.4pp) and ESPO pushes FS-DFM to 87.1% (+18.6pp).
  540. - **Key finding**: The appropriate RL formulation is architecture-dependent. ELBO-based optimization (ESPO) produces concentrated distributions across architectures, while per-step trajectory methods produce multimodal distributions.
  541. - **Paper**: [Concentrate or Collapse: When Reinforcement Learning Meets Diffusion Language Models for Web Planning](https://www.researchgate.net/profile/Muhammad-Enrizky-Brillian)
  542. - **Models**: [10 trained models on HuggingFace](https://huggingface.co/billyenrizky) including ReFusion-8B-MDPO, FS-DFM-1.3B-ESPO-mu8, and more
  543. ### Reproducing RL Experiments
  544. All training code is in `infra/training/`. Training runs on a single NVIDIA A10G GPU (24GB VRAM) via Anyscale.
  545. ```bash
  546. # Study 1: Autoregressive RL (Qwen3-8B)
  547. # SFT phase -- QLoRA fine-tuning on 992 FormFactory demonstrations (2-4 hours)
  548. python infra/training/finetuning/sft_trainer.py
  549. # Online GRPO phase -- browser-in-the-loop reward (4-8 hours per epoch)
  550. # Requires headless Chromium + FormFactory forms server
  551. python infra/training/shared/formfactory_server.py & # Start form server
  552. python infra/training/finetuning/online_grpo_trainer.py
  553. # Evaluate SFT and GRPO checkpoints on val/test splits
  554. python infra/training/finetuning/eval_sft.py
  555. # Study 2: Diffusion LM RL (ReFusion 8B, FS-DFM 1.3B)
  556. # SFT phase
  557. python infra/training/flow_matching/fsdfm_sft_trainer.py # FS-DFM SFT
  558. python infra/training/flow_matching/flow_sft_trainer.py # ReFusion SFT
  559. # Sequence-level RL (best results)
  560. python infra/training/flow_matching/espo_fsdfm_trainer.py # ESPO on FS-DFM
  561. python infra/training/flow_matching/espo_refusion_trainer.py # ESPO on ReFusion
  562. python infra/training/flow_matching/mdpo_fsdfm_trainer.py # MDPO on FS-DFM
  563. python infra/training/flow_matching/mdpo_refusion_trainer.py # MDPO on ReFusion
  564. # Submit jobs to Anyscale cloud
  565. python infra/training/anyscale/submit_job.py --config infra/training/anyscale/online_grpo_job.yaml
  566. # Push trained checkpoints to HuggingFace
  567. python infra/training/anyscale/push_checkpoints_to_hf.py
  568. # Serve trained model locally via vLLM or Ollama
  569. python infra/training/serving/serve_vllm.py
  570. python infra/training/serving/export_gguf.py # Export to GGUF for Ollama
  571. ```
  572. Reward function (in `infra/training/shared/reward_functions.py`): composite score = 0.4 * task completion + 0.4 * field accuracy + 0.2 * execution completeness. Online reward (`online_reward.py`) launches headless Chromium, executes the model's action plan, and computes the score from live browser state.
  573. ## Contributing
  574. Contributions are welcome! Please:
  575. 1. Fork the repository
  576. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  577. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  578. 4. Push to the branch (`git push origin feature/amazing-feature`)
  579. 5. Open a Pull Request
  580. ## License
  581. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  582. ## Contact
  583. - **Email**: billy.suharno@gmail.com
  584. - **GitHub**: [@billy-enrizky](https://github.com/billy-enrizky)
  585. - **Repository**: [github.com/billy-enrizky/openbrowser-ai](https://github.com/billy-enrizky/openbrowser-ai)
  586. - **Documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)
  587. ---
  588. **Made with love for the AI automation community**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.