Skip to content
Back to search

AgentBrowse

Stealth-capable browser CLI and MCP server for AI agents, with a Burp proxy slot, challenge detection and human handoff.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/psychedelic-pwner--agentbrowse/badge.svg)](/listings/psychedelic-pwner--agentbrowse)

HTML

<a href="/listings/psychedelic-pwner--agentbrowse"><img src="/api/listings/psychedelic-pwner--agentbrowse/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.

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/playwright install chromium

Stealth engine, optional:

.venv/bin/pip install patchright && .venv/bin/patchright install chromium

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.

README.md · README · 93 lines
  1. <!-- this tool detects challenges and hands them to a human; it does not defeat them. -->
  2. # agentbrowse
  3. A browser an AI agent can drive, with a slot for Burp in the middle. Phase 1 wraps Chromium (Playwright) and an optional stealth backend (patchright) behind one CLI: GET a URL, snapshot the page, keep a profile.
  4. This tool detects challenges and hands them to a human; it does not defeat them.
  5. ## Install
  6. ```bash
  7. python3 -m venv .venv
  8. .venv/bin/pip install -e ".[dev]"
  9. .venv/bin/playwright install chromium
  10. ```
  11. Stealth engine, optional:
  12. ```bash
  13. .venv/bin/pip install patchright && .venv/bin/patchright install chromium
  14. ```
  15. ## Use
  16. ```bash
  17. .venv/bin/python -m agentbrowse open https://example.com/ --json
  18. .venv/bin/python -m agentbrowse open https://target.example/ --headed --proxy http://127.0.0.1:8080 --insecure --profile burp
  19. .venv/bin/python -m agentbrowse snap --json
  20. .venv/bin/python -m agentbrowse profiles list
  21. .venv/bin/python -m agentbrowse profiles delete burp --force
  22. .venv/bin/python -m agentbrowse open https://target.example/ --challenge-report
  23. .venv/bin/python -m agentbrowse open https://target.example/ --headed --pause-for-human
  24. .venv/bin/python -m agentbrowse open https://target.example/ --geo US --proxy-pool proxies.yaml
  25. .venv/bin/python -m agentbrowse open https://target.example/ --flare-solverr http://127.0.0.1:8191
  26. .venv/bin/python -m agentbrowse mcp --proxy http://127.0.0.1:8080 --insecure --profile burp
  27. ```
  28. `--insecure` sets Playwright `ignore_https_errors` so Burp's MITM certificate is accepted. `--proxy` takes `http://127.0.0.1:8080`, `127.0.0.1:8080`, or `socks5://user:pass@host:1080`.
  29. `--challenge-report` prints the detection and nothing else. A detected challenge that is not cleared exits **4**. In a headless session the message is `run again with --headed --pause-for-human`. `--pause-for-human` only waits; it does not solve the interstitial. `--geo` reads a user-supplied YAML or JSON pool (`[{country, url}]`) and does not ship any proxies. `--flare-solverr` points at a FlareSolverr you already run. If that process is down, `open` continues.
  30. Profiles live in `~/.agentbrowse/profiles/<name>` (override the root with `AGENTBROWSE_HOME`). Each command is one-shot: `open` launches Chromium, GETs the URL, prints a snapshot, and closes. `snap` relaunches that profile and GETs the saved URL. The state file stores profile name, URL (userinfo stripped), headless, and the insecure flag. It does not store proxy credentials or cookies.
  31. Cookie export/import uses Playwright storage state (`export_cookies` / `import_cookies`).
  32. ## Use with AI agents
  33. `agentbrowse mcp` is a long-running MCP server. Transport is newline-delimited JSON-RPC 2.0 on stdio: one JSON object per line. stdout is reserved for protocol messages. The startup line `agentbrowse MCP server on stdio` goes to stderr. The browser starts on the first `browser_open`.
  34. ```json
  35. {
  36. "mcpServers": {
  37. "agentbrowse": {
  38. "command": "agentbrowse",
  39. "args": ["mcp", "--profile", "burp", "--proxy", "http://127.0.0.1:8080", "--insecure"]
  40. }
  41. }
  42. }
  43. ```
  44. Add `--headed` when the window should be visible. Flags match `open`: `--headed`, `--proxy SPEC`, `--profile NAME`, `--insecure`.
  45. | Tool | Arguments | Returns |
  46. | --- | --- | --- |
  47. | `browser_open` | `url` | snapshot (`url`, `title`, `challenge`, `text`, `elements`, `console_errors`) |
  48. | `browser_snapshot` | | the same snapshot |
  49. | `browser_click` | `selector` | `ok`, `url`, `title` |
  50. | `browser_type` | `selector`, `text`, optional `submit` | `ok`, `url` |
  51. | `browser_screenshot` | `path` | `ok`, `path` |
  52. | `browser_evaluate` | `expression` | `ok`, `result` |
  53. | `browser_cookies` | | `cookies`: `name`, `domain`, `path`, `expires` |
  54. | `browser_close` | | `ok` |
  55. `browser_cookies` is redacted on purpose. Values are credentials and are never returned. `browser_evaluate` runs in the page; an expression containing `require(`, `process.`, or `import(` is refused.
  56. ## Limits
  57. - The one-shot `open` command is GET navigation. The MCP server can click, type, screenshot, and evaluate in the page. `submit` on `browser_type` presses Enter.
  58. - `challenge` on a snapshot is `null` on a clean page, or `{kind, confidence, evidence, suggested_action}` when an interstitial is detected.
  59. - Exit code 4 means a challenge was detected and not cleared. The tool does not solve captchas.
  60. - Default engine is `chromium`. `create_engine("stealth")` uses patchright and raises `EngineUnavailable` with an install hint if it is missing.
  61. ## Tests
  62. ```bash
  63. .venv/bin/python -m pytest -q
  64. ```
  65. Tests bind `127.0.0.1` only. The browser test skips if Chromium was not installed.
  66. ## Credits
  67. See [CONTRIBUTORS.md](CONTRIBUTORS.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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