How CloakBrowser Automatically Detects Timezone and Locale from Proxy Exit IP

CloakBrowser resolves a proxy's exit IP through HTTP requests or SOCKS5 tunnels, queries a local MaxMind GeoLite2 database to determine the geographic location, and automatically injects the appropriate timezone and locale values into the browser launch options.

CloakBrowser is an open-source browser automation library that enhances Puppeteer and Playwright with advanced anti-detection features. One of its core capabilities is the ability to automatically detect timezone and locale from proxy exit IP, ensuring that browser fingerprints match the geographic location of the proxy server without manual configuration. This process runs automatically when the geoip flag is enabled and a proxy is configured.

How the Detection Pipeline Works

The detection system operates in three distinct stages: resolving the proxy's exit IP, mapping that IP to geographic metadata using a local database, and merging the discovered values with the user's launch options. All logic is centralized in js/src/geoip.ts, with supporting utilities in js/src/proxy.ts and type definitions in js/src/types.ts.

Resolving the Proxy Exit IP

The system first determines the public-facing IP address of the configured proxy using the resolveExitIp function (lines 31‑74 of js/src/geoip.ts). The approach depends on the proxy protocol:

• SOCKS5 proxies: The library loads socks-proxy-agent and issues an HTTPS request through the tunnel to a public IP-echo service such as api.ipify.org, checkip.amazonaws.com, or ifconfig.me/ip.
• HTTP/HTTPS proxies: It opens a CONNECT tunnel to the same echo services and reads the returned IP address from the response body.

If the exit IP cannot be obtained through these methods, the system falls back to resolveProxyIp (lines 94‑112), which performs a simple DNS lookup of the proxy hostname.

Downloading and Querying the MaxMind GeoLite2 Database

Once the exit IP is known, the system ensures a local copy of the MaxMind GeoLite2-City database exists. The ensureGeoipDb function (line 40 of js/src/geoip.ts) downloads the approximately 70 MiB database from a public mirror on first use and caches it under ~/.cloakbrowser/geoip/.

The resolveProxyGeo function (lines 55‑84) then uses mmdb-lib (Reader) to query this database for the exit IP record. From the returned record, it extracts:

• timezone from result.location.time_zone
• Country ISO code from result.country.iso_code

The country code is converted to a BCP-47 locale using the static COUNTRY_LOCALE_MAP table defined in lines 26‑42 of the same file.

Merging Auto-Detected Values with Launch Options

The maybeResolveGeoip helper (lines 322‑342 of js/src/geoip.ts) orchestrates the entire flow. Called by the Puppeteer and Playwright wrappers before browser launch, it performs the following steps when options.geoip is true and a proxy is defined:

1. Extracts the proxy URL using extractProxyUrl.
2. Runs resolveProxyGeo to obtain the timezone, locale, and exit IP.
3. User values take precedence: The detected timezone is used only if options.timezone is undefined. Similarly, the detected locale is used only if options.locale is not already set.
4. Returns the exit IP as a convenience for subsequent WebRTC spoofing operations.

Even when both timezone and locale are preconfigured by the user, the function still resolves the exit IP so that the --fingerprint-webrtc-ip=auto flag can be replaced with the actual address later in the launch sequence.

Implementation Code Examples

Enabling Auto-Detection

To enable automatic timezone and locale detection, set geoip: true in your launch options:

import { launch } from "cloakbrowser";

// Basic usage – the wrapper will fill timezone & locale from the proxy.
await launch({
  proxy: "http://user:pass@my-proxy.example:3128",
  geoip: true,          // turn on GeoIP auto‑detection
  stealthArgs: true,    // keep default stealth fingerprints
});

Inspecting Resolved Values

You can call the internal helper directly to preview what values will be injected:

import { maybeResolveGeoip } from "cloakbrowser/js/src/geoip.js";

const opts = {
  proxy: "socks5://my-socks-proxy:1080",
  geoip: true,
};

const result = await maybeResolveGeoip(opts);
console.log(result);
// → { timezone: 'America/New_York', locale: 'en-US', exitIp: '34.210.12.7' }

Using Resolved Values for WebRTC Spoofing

The detected exit IP can be passed to WebRTC spoofing arguments to ensure the browser reports the same IP as the proxy:

await launch({
  proxy: "http://my-proxy:8080",
  geoip: true,
  args: ["--fingerprint-webrtc-ip=auto"], // auto‑replaced with the real IP
});

Key Source Files and Functions

File	Role
[js/src/geoip.ts](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts)	Implements IP resolution (resolveExitIp, resolveProxyIp), GeoIP DB download (ensureGeoipDb), lookup logic (resolveProxyGeo), and the maybeResolveGeoip helper that injects timezone/locale.
[js/src/proxy.ts](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/proxy.ts)	Provides utilities for normalising proxy URLs (ensureProxyScheme) and extracting the hostname/IP used by the GeoIP logic.
[js/src/types.ts](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/types.ts)	Defines the LaunchOptions fields (geoip, timezone, locale, proxy) that the GeoIP feature reads and populates.

Summary

• Three-stage pipeline: Exit IP resolution → MaxMind GeoLite2 lookup → option merging.
• Protocol support: Works with SOCKS5 (via socks-proxy-agent) and HTTP/HTTPS (via CONNECT tunnels).
• Offline caching: Downloads the 70 MiB GeoLite2-City database once to ~/.cloakbrowser/geoip/ and reuses it.
• User override: Explicit timezone or locale values in launch options always take precedence over auto-detected values.
• WebRTC integration: The resolved exit IP is available for subsequent WebRTC IP spoofing even when timezone/locale are manually configured.

Frequently Asked Questions

What happens if the proxy exit IP cannot be detected?

If the HTTP/SOCKS request to the echo service fails, CloakBrowser falls back to resolveProxyIp, which performs a DNS lookup of the proxy hostname. If this also fails, the geoip auto-detection gracefully skips the timezone and locale injection, allowing the browser to launch with default or user-supplied values.

Does CloakBrowser download the GeoIP database every time?

No. The ensureGeoipDb function downloads the MaxMind GeoLite2-City database only on first use and caches it locally under ~/.cloakbrowser/geoip/. Subsequent launches use the cached file until it is manually deleted or the library updates to a newer database version.

Can I override the auto-detected timezone or locale?

Yes. The maybeResolveGeoip function always checks for existing user values before applying auto-detected data. If options.timezone or options.locale are already defined in your launch options, those values are preserved and the detected values are ignored.

Which proxy protocols support exit IP detection?

The system supports SOCKS5, HTTP, and HTTPS proxies. SOCKS5 detection uses the socks-proxy-agent library to tunnel requests, while HTTP/HTTPS proxies use standard CONNECT tunneling to reach the public IP-echo services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}