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

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 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. 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 (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 (lines 33-38), the launch wrapper performs a safety check:

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, 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:

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:

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:

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 – Contains maybeResolveGeoip, resolveExitIp, and resolveWebrtcArgs functions that handle IP resolution and argument construction
• 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 – Implements identical resolution logic for Playwright-based launches
• js/src/proxy.ts – Utility functions for parsing proxy URLs and handling SOCKS5 credential reconstruction
• 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 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 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.

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.

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