Skip to content

Proxies and geoip

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

Auto-match a proxy's region (geoip)

geoip is on by default (since SDK 0.66.0): with a proxy the SDK resolves the proxy's exit IP, and without one this machine's own public 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). By default a region that can't be resolved prints a warning and the launch goes ahead. Pass geoip: true and the launch stops with a GeoipError instead of quietly starting on this machine's clock and language; set both timezone and acceptLanguage to launch anyway. That lookup gets 20 seconds (CLEARCOTE_GEOIP_TIMEOUT_SECONDS); in .NET the error is GeoipException. With geoip: false (or CLEARCOTE_GEOIP=0) and no explicit timezone, the timezone follows the language — en-US means New York, even behind a German proxy. On the open build behind a proxy, the default lookup leaves the WebRTC address unset, because a WebRTC address there lets WebRTC UDP leave on your own connection; pass geoip: true to set it anyway.

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. Clearcote 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

Works on every build from 151, the free open build included. Open builds before 151 can't authenticate to a SOCKS5 proxy, so with those use a local relay or an HTTP proxy.

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.

Save proxy traffic on fresh profiles (httpCacheDir)

A fresh profile starts with an empty cache, so every run downloads the site's scripts, styles and images again through your proxy. From SDK 0.68.7, httpCacheDir / http_cache_dir / HttpCacheDir keeps only the HTTP cache in a folder that outlives the run. Cookies and storage are still new every run; only cached files carry over.

from clearcote import launch

# a fresh profile every run; the cached files stay in /data/http-cache/acct-1
browser = launch(proxy={"server": PROXY}, http_cache_dir="/data/http-cache/acct-1")
  • Measured on two script-heavy pages through a byte-counting proxy: about 7.7 MB of proxy traffic per run without it, about 0.4 MB once the cache is warm, in Python, Node and .NET alike.
  • Browsers running at the same time each get their own slot in the folder (slot-0, slot-1, …), because Chromium lets only one browser use a cache at once. Each slot stays warm for the next run. The three SDKs use the same layout, so they can share a folder.
  • Only share a folder between runs that may look like the same visitor. A site can link two sessions through what they have cached. Use one folder per identity (persona, proxy, account) when that matters.
  • It needs a profile: launch() (its default throwaway profile), userDataDir, launchPersistentContext() and serve() take it, and in .NET LaunchEphemeralProfileAsync, LaunchPersistentContextAsync and ServeAsync. A launch without a profile (ephemeralProfile: false, Python's async launch(), .NET's LaunchAsync) keeps its cache in memory, so it refuses the option instead of saving nothing.
  • Local launches only: a cloud or Docker launch refuses it. Passing your own --disk-cache-dir in args as well is refused too.