Install

Frankensurf is a Python package and needs Python 3.12 or newer. Pick your system:

Linux

1. Install the package with the MCP extra.

   python3 -m venv ~/.venvs/frankensurf && source ~/.venvs/frankensurf/bin/activate
   pip install "frankensurf[mcp]"

2. Download Chromium and the free stealth browsers (Camoufox, Scrapling, Patchright). This takes a few minutes.

   frankensurf setup

   If Chromium won’t start, install its system libraries: sudo $(which python) -m playwright install-deps chromium.

3. Read a page, and see each tool it tried.

   frankensurf read "https://www.walmart.com/search?q=air+fryer" --explain

macOS

1. Install Python 3.12 or newer if you don’t have it, for example with Homebrew: brew install [email protected].

2. Install the package, then Chromium and the free stealth browsers.

   python3 -m venv ~/.venvs/frankensurf && source ~/.venvs/frankensurf/bin/activate
   pip install "frankensurf[mcp]"
   frankensurf setup

3. Read a page, and see each tool it tried.

   frankensurf read "https://www.walmart.com/search?q=air+fryer" --explain

Caution

macOS isn’t part of our test runs yet. The core install is plain Python and Playwright, so it should behave as on Linux; please open an issue if it doesn’t.

Windows

Frankensurf runs inside WSL (Windows Subsystem for Linux).

1. Install WSL with Ubuntu from an administrator PowerShell, then restart.

   wsl --install -d Ubuntu

2. Open Ubuntu from the Start menu and follow the Linux steps there:

   sudo apt install -y python3-venv
   python3 -m venv ~/.venvs/frankensurf && source ~/.venvs/frankensurf/bin/activate
   pip install "frankensurf[mcp]"
   frankensurf setup
   sudo $(which python) -m playwright install-deps chromium
   frankensurf read "https://www.walmart.com/search?q=air+fryer" --explain

Your agent on Windows starts the server through WSL; see Add to your agent.

That is the free stack: plain HTTP, markdown negotiation, Jina Reader, a local Chromium and the stealth browsers. No account or key. On the 152-site benchmark it reads 73.7% of sites; adding the paid tools takes it to 89.5%. Skip the stealth browsers with frankensurf setup --no-stealth.

Working on Frankensurf itself? Install from a clone instead: git clone https://github.com/yail259/frankensurf.git, then pip install -e '.[test,mcp]' and frankensurf setup.

Optional extras

Each one adds tools to the escalation ladder. The scripts run in a shell (on Windows, inside WSL); SearXNG and Steel need Docker.

Add	Command
Local search (SearXNG)	bash scripts/start-search.sh
Self-hosted browser (Steel)	bash scripts/start-steel.sh
Stealth browsers (Camoufox, Scrapling, Patchright)	frankensurf setup (included above)
Crawl4AI	bash scripts/install-crawl4ai-provider.sh
Paid services	Add keys

Tip

Next, add Frankensurf to your agent.