How it picks a tool

The idea: a ladder

Think of every way to fetch a page as a step on a ladder. Low steps are cheap and fast. High steps are slower but get through more. Frankensurf starts low and climbs only when a step fails.

Step	How it fetches
0	A recent saved copy
1	An official API or data feed
2	Asking the site for a clean markdown version, or a signed request that identifies a trusted agent
3	A plain HTTP request
4	A lightweight JavaScript runner
5	A real browser on your machine (like Steel)
6	A hosted browser service
7	A stealth browser that looks like a person (like Camoufox or Scrapling)
8	An unblocking service, proxies or a CAPTCHA solver
9	Your own logged-in Chrome
10	An AI agent that looks at the page
11	Asking you (for 2FA or a confirmation)

It doesn’t always start at the bottom. Once memory is built, it starts at the step that worked last time on that site. It skips steps that can’t do the job, such as plain HTTP for a page that needs your login.

If a site blocks it, it climbs to a stronger step. You can tell it to stop instead, but by default it keeps going.

How it works today

Right now the order is fixed in Runtime.read (src/frankensurf/runtime.py):

Normal

Plain HTTP first, then Steel (if you set it up), then a local browser. If plain HTTP returns an empty page that needs JavaScript, it moves on to a browser.

render=True

Skips plain HTTP. Steel, then a local browser.

As you

Only your own logged-in Chrome.

Tool chosen

Exactly the tool you asked for.

Some sites have a preferred tool hard-coded, because it was measured to work better there:

Site	Preferred tool
Gumtree	Scrapling
Trading Post	Camoufox
Carsales	Camoufox
Depop	Camoufox
Cash Converters	Camoufox
eBay AU	Camoufox

These only apply when the stealth browsers are installed, and choosing a tool yourself always wins. Later, memory replaces this list: Frankensurf will learn these preferences by itself.

A limit that's going away

Today, if a site blocks a request (HTTP 401, 403 or 429, or a challenge page), Frankensurf stops trying that site for the rest of the run. In the new design this becomes a setting that defaults to climbing to a stronger step.

Plugins

Everything you might want to swap or add will be a plugin. There are five kinds.

Kind	What it does	Examples
Fetchers	Get the page	Plain HTTP, Steel, a local browser, Camoufox, Scrapling, an unblocking service, a hosted browser, an AI agent
Add-ons	Step in before or after any fetch	Proxy rotation, CAPTCHA solving, signed requests, asking for markdown, trimming output for the model
Search	Find pages	SearXNG, Bing, DuckDuckGo, search APIs
Site parsers	Pull clean data from specific sites	gumtree_listing, carsales_gallery, shopify_product
Login storage	Keep browser profiles and secrets	Your local Chrome profile, your OS keychain

Each fetcher describes itself: what it can do, whether it handles logins or stealth, what it costs and what it needs installed. The router uses that plus real measurements to choose.

A plugin can run inside Frankensurf or in its own separate process, so tools with clashing requirements can live side by side. The stealth browsers already work this way (see provider_worker.py).

Frankensurf never installs anything by itself while it’s running. New plugins get benchmarked before they become a default.

Note

Plugins are on the way. For now, the tools above are built into runtime.py and experimental.py.