Frankensurf

https://github.com/yail259/frankensurf
Admin
Frankensurf provides a single read() call for AI agents stitched from 28 web tools, trying the...
Tokens:125,099
Snippets:920
Trust Score:7.7
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install and use the example provider plugin

Source: https://github.com/yail259/frankensurf/blob/main/examples/frankensurf-plugin-example/README.md

Install the plugin into Frankensurf's environment, list plugins, trust the provider, set the EXAMPLE_API_URL and EXAMPLE_API_KEY environment variables, and read a page using the example_fetch provider with the --paid flag.

```bash
pip install -e examples/frankensurf-plugin-example   # into Frankensurf's environment
frankensurf plugins                                   # listed as PLUGIN_NOT_TRUSTED
frankensurf plugins trust provider example_fetch frankensurf-plugin-example
export EXAMPLE_API_URL=https://your-service.example/read EXAMPLE_API_KEY=...
frankensurf read https://example.com --provider example_fetch --paid
```

--------------------------------

### Install Frankensurf with uv or pipx and run initial commands

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Installs the frankensurf command and frankensurf-mcp for agents using uv tool install or pipx install. Then runs frankensurf install and an example read command.

```bash
uv tool install "frankensurf[mcp]"     # or: pipx install "frankensurf[mcp]"
frankensurf install
frankensurf read "https://news.ycombinator.com" --explain
```

--------------------------------

### Install Frankensurf and read a page

Source: https://github.com/yail259/frankensurf/blob/main/README.md

Installs Frankensurf with MCP support, installs all free tools, and reads a Walmart search page with explanation. The read command climbs through tools until it gets the real page, as shown in the output.

```bash
pip install "frankensurf[mcp]"
frankensurf install        # every free tool: browsers, stealth browsers, local search, Crawl4AI
frankensurf read "https://www.walmart.com/search?q=air+fryer" --explain
```

```text
https://www.walmart.com/search?q=air+fryer
  ✗ http                   CAPTCHA                0.4s
  ✗ local                  CAPTCHA                1.5s
  ✓ camoufox               got the page           15.6s

air fryer - Walmart.com
24,192 characters via camoufox, complete (107 results), free
```

--------------------------------

### Install, stop, and uninstall SearXNG with frankensurf CLI

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/searxng.mdx

Commands to install and start SearXNG (about 140 MB, a few seconds), stop or check status, and remove it. The install downloads a pinned commit, verifies SHA-256, installs Python packages in its own environment, and runs it in the background on 127.0.0.1:8088 with JSON output.

```bash
frankensurf install search        # install and start it (about 140 MB, a few seconds)
frankensurf search-engine stop    # any time; also: start, status
frankensurf uninstall search      # remove it
```

--------------------------------

### Install and run the Astro site

Source: https://github.com/yail259/frankensurf/blob/main/site/README.md

Install dependencies, run the dev server on http://localhost:4322, or build the static output into dist/.

```bash
npm install
npm run dev      # http://localhost:4322
npm run build    # static output in dist/
```

--------------------------------

### Install Frankensurf from a clone for development

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Clones the repository and installs with pip in editable mode including test and mcp extras, then runs frankensurf install.

```bash
git clone https://github.com/yail259/frankensurf.git
pip install -e '.[test,mcp]'
frankensurf install
```

--------------------------------

### Set up development environment and run tests

Source: https://github.com/yail259/frankensurf/blob/main/README.md

Creates a Python virtual environment, installs the package with test and MCP extras, installs Frankensurf, and runs the test suite with PYTHONPATH set to include the source directory.

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[test,mcp]'
.venv/bin/frankensurf install
PYTHONPATH=.:src .venv/bin/pytest -q
```

--------------------------------

### Install optional extras: nodriver, Steel, SOCKS

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Commands to install optional extras: nodriver via frankensurf install, Steel via a script, and SOCKS support via pip or uv tool install.

```bash
frankensurf install nodriver
```

```bash
bash scripts/start-steel.sh
```

```bash
pip install "frankensurf[socks]"
```

```bash
uv tool install "frankensurf[mcp,socks]"
```

--------------------------------

### Install Frankensurf on Windows via WSL

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Installs Python venv support, creates a virtual environment, installs the package with the MCP extra, installs tools with system dependencies, and reads a page. This is the second step for Windows users, run inside Ubuntu.

```bash
sudo apt install -y python3-venv
python3 -m venv ~/.venvs/frankensurf && source ~/.venvs/frankensurf/bin/activate
pip install "frankensurf[mcp]"
frankensurf install --with-deps
frankensurf read "https://www.walmart.com/search?q=air+fryer" --explain
```

--------------------------------

### Installation commands for the plugin

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/more/plugins.mdx

Shows how to install the plugin into Frankensurf's environment using pip, uv tool, or pipx inject.

```bash
pip install -e ./frankensurf-plugin-example                        # pip or a venv
uv tool install frankensurf --with-editable ./frankensurf-plugin-example   # uv tool
pipx inject frankensurf -e ./frankensurf-plugin-example            # pipx
```

--------------------------------

### Install Browser Use SDK in a virtual environment

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/browser-use.mdx

Creates a Python virtual environment and installs the pinned SDK from requirements-browser-use.txt.

```bash
python3 -m venv ~/.local/share/frankensurf/agent-venv
~/.local/share/frankensurf/agent-venv/bin/python -m pip install -r requirements-browser-use.txt
```

--------------------------------

### Install Frankensurf with MCP extra and tools on macOS

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Creates a virtual environment, installs the package with the MCP extra, and then installs every free tool. This is the second step in the macOS installation workflow.

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

--------------------------------

### Install WSL with Ubuntu on Windows

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Installs WSL with Ubuntu from an administrator PowerShell. This is the first step for Windows users.

```powershell
wsl --install -d Ubuntu
```

--------------------------------

### Example .env file with API keys

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/blocked/paid-tools.mdx

Example of a .env file at ~/.config/frankensurf/.env containing API keys for ZenRows, Firecrawl, and Exa. The file should be readable only by you (chmod 600). Keys never appear in results, receipts, or errors.

```bash
FRANKENSURF_ZENROWS_API_KEY=...
FRANKENSURF_FIRECRAWL_API_KEY=...
FRANKENSURF_EXA_API_KEY=...
```

--------------------------------

### Install Frankensurf with MCP extra on Linux

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Creates a virtual environment and installs the frankensurf package with the MCP extra. This is the first step in the Linux installation workflow.

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

--------------------------------

### Install frankensurf package and browsers

Source: https://github.com/yail259/frankensurf/blob/main/plugin/README.md

Install the frankensurf package with MCP extras and set up free browsers and the local search engine.

```bash
pip install "frankensurf[mcp]"     # or: uv tool install "frankensurf[mcp]"
frankensurf install                # the free browsers and the local search engine
```

--------------------------------

### Install Frankensurf tools with system dependencies on Linux

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/install.mdx

Installs every free tool and the system libraries the browsers need. This command asks for sudo and takes a few minutes.

```bash
frankensurf install --with-deps
```

--------------------------------

### Set up self-hosted Steel

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/steel.mdx

Starts the self-hosted Steel container and sets the environment variable to point Frankensurf at it.

```bash
bash scripts/start-steel.sh
export FRANKENSURF_STEEL_URL=http://127.0.0.1:3100
```

--------------------------------

### Install Chromium for Playwright

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/local-chromium.mdx

Installs the Chromium browser binary required by the `local` provider. Run this in your virtual environment before using the provider.

```bash
.venv/bin/playwright install chromium
```

--------------------------------

### Model factory example for Browser Use

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/browser-use.mdx

Example model factory file that creates a ChatOpenAI model wrapped in ModelBinding with billing set to 'paid'.

```python
from browser_use import ChatOpenAI
from frankensurf.browser_use_binding import ModelBinding

def create_model():
    return ModelBinding(ChatOpenAI(model="gpt-4.1-mini", max_retries=0), billing="paid")
```

--------------------------------

### Example receipt JSON

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/reference/receipts.mdx

A trimmed example of a receipt from a real read. It shows the structure and typical fields like trace_id, status, operation, method, observed_at, freshness_seconds, cache_hit, requested_url, final_url, http_status, latency_ms, cost_usd, evidence, attempts, and routing. The routing.provider_plan.ordered lists the planned route after skipping unavailable providers.

```json
{
  "trace_id": "6f1c…",
  "status": "observed",
  "operation": "read",
  "method": "local",
  "observed_at": "2026-10-06T03:14:07Z",
  "freshness_seconds": 0,
  "cache_hit": false,
  "requested_url": "https://example.com",
  "final_url": "https://example.com/",
  "http_status": 200,
  "latency_ms": 2267,
  "cost_usd": 0,
  "evidence": [{"path": "state/evidence/2a8c….html", "sha256": "2a8c…", "bytes": 23}],
  "attempts": [
    {"provider": "http", "status": "failed", "failure": "VISUAL_REQUIRED", "latency_ms": 90},
    {"provider": "local", "status": "observed", "latency_ms": 2176}
  ],
  "routing": {"provider_plan": {
    "ordered": ["http", "local", "camoufox", "scrapling", "scrapling_http", "crawl4ai", "jina_reader"],
    "basis": "registration order; insufficient exact-scope evidence"
  }}
}
```

--------------------------------

### Install Crawl4AI provider

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/crawl4ai.mdx

Installs the Crawl4AI provider. On Linux (or WSL on Windows), not on macOS yet. Creates `~/.local/share/frankensurf/crawl4ai-venv` and ends with a live render check. Can be moved with `FRANKENSURF_CRAWL4AI_DIR`, `FRANKENSURF_CRAWL4AI_PYTHON`, and `FRANKENSURF_CRAWL4AI_BROWSERS_PATH`.

```bash
frankensurf install crawl4ai      # part of plain `frankensurf install` too
```

--------------------------------

### Discover a site module (Python, CLI, MCP)

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/read/site-modules.mdx

Use `module discover` to draft a module from the best list of items found on a page. The Python example shows getting drafts and saving with `save=True`; the CLI and MCP equivalents are shown. Check the sample before saving, as drafts can pick the wrong list.

```python
found = await web.discover_module("https://www.example.com/search?q=lamp")
best = found["drafts"][0]          # module, count, fields, sample
await web.discover_module("https://www.example.com/search?q=lamp", save=True)
```

```bash
frankensurf module discover "https://www.example.com/search?q=lamp" --save
```

```json
{ "tool": "discover_site_module", "arguments": { "url": "https://www.example.com/search?q=lamp", "save": true } }
```

--------------------------------

### Initialize key and print public directory

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/blocked/signed-requests.mdx

Run these commands to create a key and output its public directory to a file named directory.json. The private key never leaves your machine.

```bash
frankensurf bot-auth-init
frankensurf bot-auth-directory > directory.json
```

--------------------------------

### Install Camoufox with frankensurf install stealth

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/camoufox.mdx

Installs Camoufox and Scrapling in a separate environment (FRANKENSURF_PROVIDER_PYTHON).

```bash
frankensurf install stealth
```

--------------------------------

### Trust and use the plugin

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/more/plugins.mdx

Commands to trust the plugin, list plugins, set environment variables, and read a URL with the provider.

```bash
frankensurf plugins trust provider example_fetch frankensurf-plugin-example
frankensurf plugins                     # now under "loaded"
export EXAMPLE_API_URL=https://your-service.example/read EXAMPLE_API_KEY=...
frankensurf read https://example.com --provider example_fetch --paid
```

--------------------------------

### Install Frankensurf for CrewAI

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/frameworks.mdx

Install the package with the crewai extra using pip.

```bash
pip install "frankensurf[crewai]"
```

--------------------------------

### Install Frankensurf for LangChain

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/frameworks.mdx

Install the package with the LangChain extra using pip.

```bash
pip install "frankensurf[langchain]"
```

--------------------------------

### Install Frankensurf for OpenAI Agents SDK

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/frameworks.mdx

Install the package with the openai-agents extra using pip.

```bash
pip install "frankensurf[openai-agents]"
```

--------------------------------

### Add and install Frankensurf plugin in Claude Code

Source: https://github.com/yail259/frankensurf/blob/main/plugin/README.md

Commands to add the plugin marketplace and install the Frankensurf plugin.

```bash
/plugin marketplace add yail259/frankensurf
/plugin install frankensurf@frankensurf
```

--------------------------------

### Install Patchright into stealth environment

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/integrations/patchright.mdx

Install Patchright into the provider virtual environment using pip. This is required before using the provider.

```bash
~/.local/share/frankensurf/provider-venv/bin/pip install patchright
```

--------------------------------

### Entry point declaration in pyproject.toml

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/more/plugins.mdx

Declares the plugin's entry point under the provider group, mapping the plugin ID to the ExampleFetch class. Includes project metadata and dependencies.

```toml
[project]
name = "frankensurf-plugin-example"
version = "0.1.0"
dependencies = ["frankensurf>=0.34", "httpx>=0.28,<1"]

[project.entry-points."frankensurf.plugins.provider"]
example_fetch = "frankensurf_plugin_example:ExampleFetch"
```

--------------------------------

### Install, show, and uninstall the FrankenSurf skill

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/agents.mdx

Commands to install the skill to the default location or a custom directory, show its contents, and uninstall it. The skill is automatically sent to MCP clients, but agents that load skills from a folder (like Claude Code) need this installation.

```bash
frankensurf skill install            # ~/.claude/skills/frankensurf/SKILL.md
frankensurf skill install --skill-dir ./my-agent/skills
frankensurf skill show
frankensurf skill uninstall          # remove it again (--skill-dir for another folder)
```

--------------------------------

### Runtime constructor

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/reference/python.mdx

Creates a Runtime instance that owns the state directory and configuration for cache, evidence, traces, route memory, and pacing. It is opened with `async with`.

```APIDOC
## Runtime(state_dir, steel_api_url, local_cdp_url, concurrency, per_domain, domain_delay, identity_registry, plugin_config_path)

### Description
Creates a Runtime instance that owns the state directory and configuration for cache, evidence, traces, route memory, and pacing. It is opened with `async with`.

### Parameters
- **state_dir** (string) - Optional - Path to the state directory for cache, evidence, traces, route memory and pacing.
- **steel_api_url** (string) - Optional - URL for a self-hosted Steel, or use FRANKENSURF_STEEL_URL environment variable.
- **local_cdp_url** (string) - Optional - Used only through a registered identity.
- **concurrency** (integer) - Optional - Number of pages at once in a batch. Default: 4.
- **per_domain** (integer) - Optional - Number of pages at once per site in a batch. Default: 1.
- **domain_delay** (number) - Optional - Seconds between batch requests to one site. Default: 0.25.
- **identity_registry** (object) - Optional - Identity registry, or use FRANKENSURF_IDENTITIES environment variable.
- **plugin_config_path** (string) - Optional - Path to plugin configuration, or use ~/.config/frankensurf/plugins.json.

### Example
```python
Runtime(
    state_dir="state",
    steel_api_url=None,
    local_cdp_url=None,
    concurrency=4,
    per_domain=1,
    domain_delay=0.25,
    identity_registry=None,
    plugin_config_path=None,
)
```
```

--------------------------------

### Use Frankensurf from Python

Source: https://github.com/yail259/frankensurf/blob/main/README.md

Shows how to use the Frankensurf Runtime in Python to read a page and perform a search.

```python
from frankensurf import Runtime

async with Runtime("state") as web:
    page = await web.read("https://example.com", policy_overrides={"prefer_markdown": True})
    hits = await web.search("playwright python tutorial")
```

--------------------------------

### receipt.attempts: automatic escalation example

Source: https://github.com/yail259/frankensurf/blob/main/site/src/content/docs/docs/read/javascript.mdx

Example of the receipt.attempts output showing automatic escalation from HTTP to a local browser when plain HTTP fails with VISUAL_REQUIRED.

```json
[
  { "provider": "http", "status": "failed", "failure": "VISUAL_REQUIRED", "latency_ms": 88 },
  { "provider": "local", "status": "observed", "latency_ms": 1310 }
]
```
Tokens:
Raw