Skip to content

Proxies and geoip

Send the browser through your own proxy, including SOCKS5 with a username and password on the licensed build, and let geoip match the timezone, language and WebRTC address to the proxy's exit IP.

Auto-match a proxy's region (geoip)

Pass geoip with a proxy and the SDK resolves the proxy's exit IP — looked up in the offline geoip-all-in-one database — and sets a coherent timezone + primary navigator language + Accept-Language + WebRTC IP for that region. No more hand-matching a timezone to every proxy:

from clearcote import launch

browser = launch(
    fingerprint="user-7423",
    proxy={"server": "http://host:8080", "username": "u", "password": "p"},
    geoip=True,  # timezone + language auto-matched to the proxy's region
)

It also sets the geolocation and the full navigator.languages list for the region, works through HTTP and SOCKS5 proxies (credentials included), and is in all three SDKs (Geoip = true in .NET). The first run downloads the database (about 50 MB). If the region can't be resolved, the launch stops with a GeoipError rather than quietly starting on this machine's clock and language; set both timezone and acceptLanguage to launch anyway. The lookup gets 20 seconds (CLEARCOTE_GEOIP_TIMEOUT_SECONDS); in .NET the error is GeoipException. Without geoip or an explicit timezone, the timezone follows the language — en-US means New York, even behind a German proxy.

Prefer to set it yourself? Use acceptLanguage (Node) / accept_language (Python), e.g. "en-US,en" — it sets the Accept-Language header, the full navigator.languages array, and navigator.language — and Intl / toLocaleString follow it too.

SOCKS5 with credentials

Stock Chromium cannot authenticate to a SOCKS5 proxy at all — it has no implementation of the username/password sub-negotiation — so the usual workaround is a local relay that holds the credentials. The licensed build implements it in the engine (RFC 1929), so no relay is needed. Pass the username and password as separate fields or inside the address (socks5://user:pass@host:port); either way the SDK hands them to the engine. Credentials inside the address need SDK 0.31.1 or newer: older SDKs let Playwright drop them, and the proxy saw no login.

from clearcote import launch_persistent_context

ctx = launch_persistent_context(
    "./profile",
    proxy={"server": "socks5://proxy.example.net:1080", "username": "user", "password": "pass"},
)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://api.ipify.org?format=json")   # confirm the exit IP is the proxy's

Needs the licensed build (Free with GitHub or Pro, engine 151 r14 or newer); the open build can't authenticate to a SOCKS5 proxy, so use a local relay or an HTTP proxy with it.

Always verify the exit address before you trust a session. A proxy that silently fails open sends traffic from your own IP, and every other precaution becomes irrelevant. Check it once at launch against an address reflector rather than assuming.