# How CloakBrowser Automatically Detects Timezone and Locale from Proxy Exit IP

> CloakBrowser automatically detects timezone and locale from proxy exit IP by resolving IP, querying a GeoLite2 database, and injecting values into browser launch options.

- Repository: [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- Tags: how-to-guide
- Published: 2026-05-09

---

**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`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts), with supporting utilities in [`js/src/proxy.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/proxy.ts) and type definitions in [`js/src/types.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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:

```js
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:

```js
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:

```js
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)](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)](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)](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.