More than one connection

Some walls block an address, not a browser. Once a site has seen enough reads from one connection, every tool on that machine meets the wall, however stealthy. If you have other connections, FrankenSurf can use them: a read that your direct connection walled gets one more pass through each of them.

Set it up

List your connections in FRANKENSURF_EGRESS, as name=url, separated by commas (newlines work in the environment, but not in ~/.config/frankensurf/.env, which reads one line per setting):

# A VPS you can SSH to is a free second connection:
ssh -N -D 1080 you@your-vps &
export FRANKENSURF_EGRESS="vps=socks5://127.0.0.1:1080, phone=http://192.168.1.20:8080"

Any HTTP or SOCKS5 proxy works: an SSH tunnel to a VPS, a proxy app on your phone’s hotspot, a residential pool. SOCKS needs the socks extra: pip install "frankensurf[socks]", or uv tool install "frankensurf[mcp,socks]" for a tool install. The pool comes from your configuration only: receipts, traces and hints name a connection (vps), never its address or credentials.

Check them: frankensurf egress check reads one small page through your direct connection and each connection in the pool, and says whether it works and where it comes out (address and country), never the connection’s URL.

A free second connection

• An SSH tunnel to any server you can log in to (a VPS, a friend’s machine, a cloud shell): ssh -N -D 1080 you@host, then vps=socks5://127.0.0.1:1080.
• Cloudflare WARP, free: register once with wgcf (wgcf register, then wgcf generate), and run wireproxy with that profile and a [Socks5] section on 127.0.0.1:40000; then warp=socks5://127.0.0.1:40000. egress check shows warp: on when it works. Walls that refuse data-centre addresses may refuse WARP’s too, so check it on the sites you need.
• Your phone’s hotspot with a proxy app on the phone.

What happens

1. A read starts on your direct connection, as always.
2. If it ends at a wall or a rate limit (egress_failures: BLOCKED, CAPTCHA, RATE_LIMITED), each connection in the pool gets one pass with egress_tools (Camoufox, Scrapling and plain HTTP by default). Tools that got past this wall vendor more often than not go first. Only tools that take a connection per read count: plain HTTP and the isolated stealth browsers (Camoufox, Scrapling, Patchright, nodriver without a password). The local browser and Steel take their proxy when they start, so they are left out. If the page then needs a stronger read, that climb goes through the same connection, with the same tools.
3. The first connection that gets the page wins, and becomes the site’s hint for a day (origin_route_hint_ttl_seconds): the next read of that site goes through it first, and falls back to the usual route if it stops working. A site cooling down after a wall (pacing) still gets its known connection, and only that.

receipt.egress appears whenever the pool was tried: used (the connection’s name, or null when none got through), tried, after (the failure that started it) and direct_trace_id (the walled direct read, whose cost stays on the bill), or from_hint: true when the site’s hint chose the connection. The read’s trace records it too.

Note

FRANKENSURF_PROXY is different: it sends every read from your machine through one proxy. The pool is a fallback, used only after a wall; a pass through a pool connection uses that connection instead, and its receipt has no via_proxy. Set use_egress_pool: false on a read to keep it on the direct connection.

Options

Option	Default	Description
FRANKENSURF_EGRESS	unset	Your other connections, name=url, comma- or newline-separated.
use_egress_pool	true	Let a walled read try the pool.
egress_failures	BLOCKED, CAPTCHA, RATE_LIMITED	Failures that start a pass through the pool.
egress_tools	camoufox, scrapling, http	Tools a pass uses (only those that take a connection per read); the wall vendor’s best go first.