# How WebRTC IP Spoofing Works with geoip=True Proxy Integration in CloakBrowser

> Discover how CloakBrowser spoofs your WebRTC IP using proxy integration and geoip=True. Learn how your proxy's exit IP is injected for enhanced privacy.

- Repository: [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- Tags: deep-dive
- Published: 2026-05-09

---

**CloakBrowser masks your real IP address in WebRTC by resolving your proxy's exit IP and injecting it into Chromium via the `--fingerprint-webrtc-ip` flag when `geoip: true` is enabled.**

CloakBrowser is an open-source browser automation library that prevents WebRTC leaks by spoofing IP addresses to match proxy exit nodes. When you enable the `geoip: true` launch option alongside a proxy configuration, the library automatically resolves the proxy's public IP and passes it to Chromium's WebRTC stack. This ensures that `RTCPeerConnection` ICE candidates reveal the proxy's IP rather than your local network address.

## The Multi-Step Resolution Pipeline

CloakBrowser implements a four-stage resolution pipeline that bridges proxy configuration with Chromium's WebRTC fingerprinting system. Each stage is handled by specific functions in the TypeScript source.

### Launch Option Parsing

When you call `launch({ proxy, geoip: true })`, the wrapper in [`js/src/puppeteer.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/puppeteer.ts) immediately prepares the resolution workflow. The library accepts both Puppeteer and Playwright-style launch options, extracting the proxy URL and GeoIP flag before spawning the browser process.

### Exit IP Detection and GeoIP Resolution

The core resolution logic resides in [`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts). The `maybeResolveGeoip` function orchestrates the detection:

1. **Proxy URL extraction** – `extractProxyUrl` normalizes the proxy configuration, handling SOCKS5 dictionaries and reconstructing credentials when necessary (lines 27-33).

2. **Tunnel-based IP echo** – `resolveExitIp` establishes a secure tunnel through the proxy to query public IP echo services. For SOCKS5 proxies, it uses the **socks-proxy-agent** package to tunnel requests to `api.ipify.org`, `checkip.amazonaws.com`, or `ifconfig.me/ip`. For HTTP/HTTPS proxies, it opens a CONNECT tunnel to the same services (lines 31-95).

The result is a GeoIP object containing `{ timezone, locale, exitIp }`, with the exit IP cached for subsequent operations.

### WebRTC Argument Preparation

Before Chromium launches, `resolveWebrtcArgs` processes the command-line arguments in [`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts) (lines 45-77). If you explicitly provided `--fingerprint-webrtc-ip=auto`, the function replaces `auto` with the resolved exit IP. If resolution fails, it removes the flag to prevent detection inconsistencies.

### Fallback Flag Injection

Even without explicit WebRTC flags, CloakBrowser ensures protection. In [`js/src/puppeteer.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/puppeteer.ts) (lines 33-38), the launch wrapper performs a safety check:

```typescript
if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
  resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
}

```

This guarantees that whenever an exit IP is resolved and no existing WebRTC flag is present, the library automatically appends `--fingerprint-webrtc-ip=<exit-ip>` to the Chromium process arguments.

## Source Code Implementation Details

### SOCKS5 vs. HTTP/HTTPS Tunneling

The `resolveExitIp` function distinguishes between proxy protocols to establish the appropriate tunnel:

- **SOCKS5 proxies** – Uses `socks-proxy-agent` to create a SOCKS5 connection to the echo services
- **HTTP/HTTPS proxies** – Opens a direct CONNECT tunnel through the proxy to reach the IP detection endpoints

This dual-path approach ensures compatibility with residential rotating proxies and corporate HTTP gateways alike.

### The resolveWebrtcArgs Function

Located in [`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts), this function sanitizes the argument array before launch. It specifically searches for the `--fingerprint-webrtc-ip=` prefix, handling three scenarios:

1. Finds `=auto` – Replaces with resolved exit IP
2. Finds existing IP – Leaves untouched (respects user override)
3. Finds no flag – Returns original array (fallback injection happens later in puppeteer.ts)

## Practical Implementation Examples

### Basic Usage with Automatic Spoofing

The most common pattern requires no explicit WebRTC flags. CloakBrowser resolves the proxy exit IP and injects the correct argument automatically:

```typescript
import { launch } from "cloakbrowser/puppeteer";

(async () => {
  const browser = await launch({
    proxy: "http://user:pass@my-proxy.example.com:3128",
    geoip: true,
  });

  const page = await browser.newPage();
  await page.goto("https://browserleaks.com/webrtc");
  // WebRTC will display the proxy exit IP, not your local IP
  await browser.close();
})();

```

### Explicit Auto-Resolution Mode

For debugging or custom workflows, you can explicitly request automatic IP resolution:

```typescript
import { launch } from "cloakbrowser/puppeteer";

(async () => {
  const browser = await launch({
    proxy: "socks5://my-socks-proxy:1080",
    geoip: true,
    args: ["--fingerprint-webrtc-ip=auto"],
  });
  // CloakBrowser replaces 'auto' with the actual exit IP before Chromium starts
})();

```

### Accessing Resolved Exit IP for Custom Logic

If you need the exit IP for logging or verification before launching the browser, use the internal resolution function directly:

```typescript
import { maybeResolveGeoip } from "cloakbrowser/geoip";

(async () => {
  const { exitIp, timezone, locale } = await maybeResolveGeoip({
    proxy: "http://proxy.example.com:8080",
    geoip: true,
  });

  console.log("Resolved for WebRTC spoofing:", exitIp);
  // Use exitIp for additional validation or logging
})();

```

## Key Source Files

Understanding the WebRTC spoofing architecture requires familiarity with these specific files in the CloakHQ/CloakBrowser repository:

- **[`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts)** – Contains `maybeResolveGeoip`, `resolveExitIp`, and `resolveWebrtcArgs` functions that handle IP resolution and argument construction
- **[`js/src/puppeteer.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/puppeteer.ts)** – Launch wrapper that ties GeoIP resolution to WebRTC flag injection (lines 33-38 contain the critical fallback logic)
- **[`js/src/playwright.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/playwright.ts)** – Implements identical resolution logic for Playwright-based launches
- **[`js/src/proxy.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/proxy.ts)** – Utility functions for parsing proxy URLs and handling SOCKS5 credential reconstruction
- **[`js/src/types.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/types.ts)** – TypeScript definitions for `LaunchOptions`, including the `geoip?: boolean` flag

## Summary

- **CloakBrowser** prevents WebRTC IP leaks by injecting proxy exit IPs into Chromium via the `--fingerprint-webrtc-ip` flag
- **`geoip: true`** triggers automatic resolution of the proxy's public IP using tunnel-based requests to echo services like ipify.org
- **`maybeResolveGeoip`** in [`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts) handles SOCKS5 agents and HTTP/HTTPS CONNECT tunnels to discover the exit IP
- **`resolveWebrtcArgs`** replaces `--fingerprint-webrtc-ip=auto` with the resolved IP, while the fallback logic in [`js/src/puppeteer.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/puppeteer.ts) adds the flag automatically if missing
- The spoofing affects all WebRTC operations, ensuring `RTCPeerConnection` ICE candidates expose the proxy address rather than the local network interface

## Frequently Asked Questions

### What happens if I use a proxy without setting `geoip: true`?

Without `geoip: true`, CloakBrowser skips the exit IP resolution step and does not automatically inject the `--fingerprint-webrtc-ip` flag. Your Chromium instance will launch with default WebRTC behavior, potentially exposing your real local IP address through ICE candidates even though HTTP traffic routes through the proxy. Always enable `geoip: true` when WebRTC privacy is required.

### Does CloakBrowser support SOCKS5 proxies for WebRTC spoofing?

Yes, CloakBrowser fully supports SOCKS5 proxies through the `socks-proxy-agent` package. When resolving the exit IP, `resolveExitIp` detects SOCKS5 URLs and creates a SOCKS5 tunnel to reach the IP echo services. This works with both authenticated and unauthenticated SOCKS5 proxies, credential reconstruction being handled by `extractProxyUrl` in [`js/src/geoip.ts`](https://github.com/CloakHQ/CloakBrowser/blob/main/js/src/geoip.ts).

### How does the `--fingerprint-webrtc-ip=auto` flag work?

When you explicitly include `--fingerprint-webrtc-ip=auto` in the launch arguments, `resolveWebrtcArgs` intercepts this placeholder during the pre-launch phase. The function awaits the GeoIP resolution result and replaces `auto` with the actual exit IP address (e.g., `--fingerprint-webrtc-ip=203.0.113.45`). If resolution fails, the flag is removed to prevent Chromium from broadcasting an invalid value.

### Can I verify which IP WebRTC is actually using?

Yes. After launching with `geoip: true`, navigate to testing sites like `browserleaks.com/webrtc` or `ipleak.net`. The WebRTC section will display the proxy's exit IP rather than your local network address. You can also programmatically access the resolved IP before launch using `maybeResolveGeoip` to log or validate the expected exit node.