When a site blocks you
Paid tools and budgets
Turn on paid browsers, unblockers and search, and cap what a read can spend.
The free stack needs no keys. Paid tools join a read only when two things are true: the key is set, and the call allows it.
- Paid tools are tried after the free ones, unless escalation moves them up.
- They are never retried automatically.
- A tool without a key is skipped, not failed.
page = await web.read(url, policy_overrides={ "allow_paid_fallbacks": True, "max_cost_usd": 0.05,}){ "tool": "read", "arguments": { "url": "https://www.g2.com/", "acquisition_policy": { "allow_paid_fallbacks": true, "max_cost_usd": 0.05 } } }receipt.cost_usd is the total measured cost. If any tool’s cost is unknown,
the total is null, never a guess.
Add keys
Section titled “Add keys”Frankensurf looks for each key in this order:
- the environment, as
FRANKENSURF_<NAME>; ~/.config/frankensurf/.env;- the
api_keysobject in~/.config/frankensurf/services.json.
FRANKENSURF_ZENROWS_API_KEY=...FRANKENSURF_FIRECRAWL_API_KEY=...FRANKENSURF_EXA_API_KEY=...Keep the file readable only by you (chmod 600). With a secrets manager such as 1Password,
Doppler or Infisical, store the keys under these names and run through it, for
example op run -- frankensurf read …. Keys never appear in results,
receipts or errors.
| Tool | Keys |
|---|---|
| Jina Reader | JINA_API_KEY (optional) |
| Firecrawl | FIRECRAWL_API_KEY |
| ZenRows | ZENROWS_API_KEY |
| Scrapfly | SCRAPFLY_API_KEY |
| Bright Data | BRIGHTDATA_API_KEY, BRIGHTDATA_ZONE |
| Browserbase | BROWSERBASE_API_KEY |
| Steel Cloud | STEEL_API_KEY |
| Hyperbrowser | HYPERBROWSER_API_KEY |
| Browserless | BROWSERLESS_API_KEY |
| Kernel | KERNEL_API_KEY |
| Anchor | ANCHOR_API_KEY |
| Cloudflare Browser Run | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
| Zyte | ZYTE_API_KEY |
| Apify | APIFY_API_TOKEN |
| fastCRW | FASTCRW_API_KEY, or FASTCRW_URL for self-hosted |
| Skyvern | SKYVERN_API_KEY |
| Exa | EXA_API_KEY |
| Brave | BRAVE_API_KEY |
| Tavily | TAVILY_API_KEY |
| Parallel | PARALLEL_API_KEY |
All prefixed with FRANKENSURF_.
Budgets
Section titled “Budgets”max_cost_usd caps the whole read, fallbacks included. Tools that can bound
their worst case (ZenRows, Firecrawl and the hosted browsers) refuse a call that
could pass what’s left, with BUDGET_EXHAUSTED. Tools that can’t report cost
don’t run under a cap.