### Run example scenarios

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Execute specific browser automation scenarios using the examples project.

```bash
dotnet run --project examples/CloakBrowser.Examples -- basic
dotnet run --project examples/CloakBrowser.Examples -- humanize
dotnet run --project examples/CloakBrowser.Examples -- visual   # on-screen cursor trail
dotnet run --project examples/CloakBrowser.Examples -- behavioral
dotnet run --project examples/CloakBrowser.Examples -- proxy-geoip
```

--------------------------------

### Usage example for binary_info

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Retrieves and prints status information about the installed binary.

```python
from cloakbrowser import binary_info

info = binary_info()
print(f"Version: {info['version']}")
print(f"Installed: {info['installed']}")
print(f"Binary: {info['binaryPath']}")
```

--------------------------------

### Install CloakBrowser for Python

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Standard installation command for the Python package.

```bash
pip install cloakbrowser
```

--------------------------------

### Basic Browser Launch

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

A minimal example demonstrating how to initialize the browser, navigate to a URL, and close the session.

```python
from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()
```

--------------------------------

### Install CloakBrowser binary

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Pre-downloads the required binary with progress tracking.

```bash
cloakbrowser install
# Downloading chromium-146.0.7680.177.5 for linux-x64...
# Verifying signature... OK
# Extracting... OK
# Binary ready at /home/user/.cloakbrowser/chromium-146.0.7680.177.5/chrome
```

--------------------------------

### Usage examples for ensure_binary

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Demonstrates downloading free/Pro binaries, pinning versions, and selecting release channels.

```python
from cloakbrowser import ensure_binary

# Ensure the free binary is available
path = ensure_binary()
print(f"Binary ready at: {path}")

# Ensure a Pro binary (validates license at server)
path = ensure_binary(license_key="cb_xxxxxxxx")

# Pin to a specific version
path = ensure_binary(browser_version="148.0.7778.215.2")

# Use preview channel (Pro only)
path = ensure_binary(license_key="cb_xxxxxxxx", release_channel="preview")
```

--------------------------------

### Install CloakBrowser

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Use the package manager for your preferred environment to install the CloakBrowser wrapper.

```bash
pip install cloakbrowser
```

```bash
npm install cloakbrowser
```

--------------------------------

### Resolve License Key Example

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Shows how to retrieve the active license key for the current session.

```python
from cloakbrowser.license import resolve_license_key

key = resolve_license_key()
if key:
    print(f"Using license: {key[:10]}...")
else:
    print("Running free (no license)")
```

--------------------------------

### Install and Manage Binaries via CLI

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Commands for pre-downloading binaries, checking diagnostics, updating, and clearing cache.

```bash
cloakbrowser install
```

```bash
cloakbrowser info              # Full diagnostics with launch test
cloakbrowser info --quick      # Skip launch test
cloakbrowser info --json       # Machine-readable output
cloakbrowser info --proxy http://proxy:8080  # Check GeoIP resolution
```

```bash
cloakbrowser update
```

```bash
cloakbrowser clear-cache
```

--------------------------------

### Configure Virtual Display for Headed Mode

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Commands to install and start Xvfb for running headed browser sessions on headless Linux environments.

```bash
# Install Xvfb (virtual framebuffer)
sudo apt install xvfb

# Start virtual display
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
```

--------------------------------

### Configure Browser Fingerprinting

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Python examples for launching the browser with specific fingerprint, platform, and GPU overrides.

```python
# Pin a seed for a persistent identity
browser = launch(args=["--fingerprint=42069"])

# Full control — disable defaults, set everything yourself
browser = launch(stealth_args=False, args=[
    "--fingerprint=42069",
    "--fingerprint-platform=windows",
])

# Override GPU to look like a specific machine
browser = launch(args=[
    "--fingerprint-gpu-vendor=Intel Inc.",
    "--fingerprint-gpu-renderer=Intel Iris OpenGL Engine",
])
```

--------------------------------

### Preview Channel Marker File Paths

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Examples of marker file paths for the Preview channel.

```text
~/.cloakbrowser/latest_pro_version_preview_linux-x64
~/.cloakbrowser/latest_pro_version_preview_darwin-arm64
```

--------------------------------

### Pro Version Marker File

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Example content for the version tracking marker file.

```text
151.0.7922.108.2
```

--------------------------------

### binaryInfo()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Retrieves metadata about the currently configured or installed binary.

```APIDOC
## binaryInfo()

### Description
Returns an object containing detailed information about the binary, including version, installation status, and paths.

### Returns
- **BinaryInfo** (object) - An object containing:
  - **version** (string) - Current version.
  - **bundledVersion** (string) - Default wrapper version.
  - **platform** (string) - Target platform.
  - **tier** ("pro" | "free") - Subscription tier.
  - **binaryPath** (string) - Path to the binary.
  - **installed** (boolean) - Whether the binary is installed.
  - **cacheDir** (string) - Local cache directory.
  - **downloadUrl** (string) - Source URL for the binary.
```

--------------------------------

### Install CloakBrowser package

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Use the dotnet CLI to add the CloakBrowser package to your project.

```bash
dotnet add package CloakBrowser
```

--------------------------------

### Validate License Example

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Demonstrates checking license validity and accessing plan details.

```python
from cloakbrowser import validate_license

info = validate_license("cb_xxxxxxxx")
if info.valid:
    print(f"Valid {info.plan} license")
    if info.expires:
        print(f"Expires: {info.expires}")
else:
    print("Invalid license")
```

--------------------------------

### binary_info()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Retrieves the current installation status and metadata for the CloakBrowser binary.

```APIDOC
## binary_info()

### Description
Check binary installation status and metadata.

### Return Value
- **dict** - Dictionary containing: version, platform, installed (bool), binaryPath, cacheDir, tier, and downloadUrl.
```

--------------------------------

### Install CloakBrowser GeoIP support

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Optional installation for auto-detecting timezone and locale from proxy IP.

```bash
pip install 'cloakbrowser[geoip]'
```

--------------------------------

### BinaryInfo Interface

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/types.md

Represents the installation status and metadata for the browser binary.

```typescript
interface BinaryInfo {
  version: string;
  bundledVersion: string;  // Wrapper's default Chromium version
  platform: string;        // e.g., "linux-x64", "darwin-arm64"
  tier: "pro" | "free";    // License tier
  binaryPath: string;      // Absolute path to the binary
  installed: boolean;      // Whether the binary exists on disk
  cacheDir: string;        // Cache directory path
  downloadUrl: string;     // URL binary would download from
}
```

--------------------------------

### Install CloakBrowser

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Commands to install CloakBrowser with either Playwright or Puppeteer dependencies.

```bash
# With Playwright
npm install cloakbrowser playwright-core

# With Puppeteer
npm install cloakbrowser puppeteer-core
```

--------------------------------

### Install Baseline Linux Fonts

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Installs essential emoji and CJK fonts required for canvas fingerprinting consistency on Linux.

```bash
sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
```

--------------------------------

### Run CloakBrowser in Docker

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Example command for passing license keys and mounting volumes when running inside a container.

```bash
docker run \
  -e CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx \
  -e CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS=10 \
  -v ~/.cloakbrowser:/root/.cloakbrowser \
  cloakhq/cloakbrowser python my_script.py
```

--------------------------------

### Install GeoIP dependency

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Install the mmdb-lib package to enable automatic timezone and locale detection based on proxy IP.

```bash
npm install mmdb-lib
```

--------------------------------

### Configure CloakBrowser via Environment Variables

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Example shell commands to set global environment variables for binary paths, licensing, version pinning, and feature timeouts.

```bash
# Use a local Chromium binary (skip download)
export CLOAKBROWSER_BINARY_PATH=/opt/chromium/chrome

# Set a Pro license globally
export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

# Pin to a specific version
export CLOAKBROWSER_VERSION=148.0.7778.215.2

# Use preview release channel for Pro
export CLOAKBROWSER_RELEASE_CHANNEL=preview

# Custom cache directory
export CLOAKBROWSER_CACHE_DIR=/data/chromium-cache

# Increase GeoIP timeout to 10 seconds
export CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS=10
```

--------------------------------

### Install Playwright system dependencies

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Install required system dependencies for Playwright without downloading the standard Chromium binary.

```bash
playwright install-deps chromium
```

--------------------------------

### Configure Windows Fonts on Linux

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Recommended font installation to improve FingerprintJS accuracy.

```bash
mkdir -p ~/.local/share/fonts/windows
cp -r /path/to/windows/Fonts/. ~/.local/share/fonts/windows/
fc-cache -f
```

--------------------------------

### Advanced CDP Server Configuration

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Examples for running the CDP server with custom proxies, headed mode, or idle timeouts.

```bash
# With proxy
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --proxy-server=http://proxy:8080
```

```bash
# Headed mode (renders to Xvfb inside container)
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --headless=false
```

```bash
# Reap disconnected per-seed browser processes after 5 minutes
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --idle-timeout=300
```

--------------------------------

### CloakBrowser CLI commands

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Manage binary installation, authentication, and cache status via the command line.

```bash
npx cloakbrowser login        # Get a free key via GitHub, or save a paid key
npx cloakbrowser logout        # Remove the saved key (revert to the free binary)
npx cloakbrowser install      # Download binary with progress output
npx cloakbrowser info         # Show version, path, platform
npx cloakbrowser update       # Check for and download newer binary
npx cloakbrowser clear-cache  # Remove cached binaries
```

--------------------------------

### Manage Binaries with Python

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Utility functions for checking binary status, ensuring installation, clearing cache, and checking for updates.

```python
from cloakbrowser import binary_info

info = binary_info()
# Returns dict with 'version', 'platform', 'installed', 'binaryPath', etc.
print(info['version'])       # e.g., "146.0.7680.177.5"
print(info['installed'])     # True/False
print(info['binaryPath'])    # Full path to chrome binary
```

```python
from cloakbrowser import ensure_binary

path = ensure_binary(license_key="cb_xxxxxxxx")
print(path)  # Absolute path to chrome binary
```

```python
from cloakbrowser import clear_cache

clear_cache()  # Removes all cached binaries
```

```python
from cloakbrowser import check_for_update

newer_version = check_for_update()
if newer_version:
    print(f"New version available: {newer_version}")
```

--------------------------------

### JavaScript/TypeScript Usage Examples

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Common usage patterns for launching browsers, contexts, and persistent profiles with various configuration options.

```javascript
import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';

// Basic
const browser = await launch();

// With options
const browser = await launch({
  proxy: 'http://user:pass@proxy:8080',
  geoip: true,
  humanize: true,
  headless: false,
});

// Context (browser + context in one call)
const ctx = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
});

// Persistent profile
const ctx = await launchPersistentContext({
  userDataDir: './my-profile',
  proxy: 'http://proxy:8080',
  headless: false,
});

const page = await ctx.newPage();
await page.goto('https://example.com');
await ctx.close();
```

--------------------------------

### Start CDP Server Mode

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Initializes a persistent stealth browser in Docker for remote CDP connections.

```bash
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve
```

--------------------------------

### Display binary diagnostics

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Shows the current binary status, version, license tier, and installation path.

```bash
cloakbrowser info
# CloakBrowser binary diagnostics
# Version: 146.0.7680.177.5 (free)
# Platform: linux-x64
# Installed: yes
# Binary: /home/user/.cloakbrowser/chromium-146.0.7680.177.5/chrome
# ...
```

--------------------------------

### Launch Browser in Headed Mode

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Example of launching the browser with headed mode and a residential proxy to bypass aggressive site protections.

```python
from cloakbrowser import launch

# Headed mode + residential proxy for maximum stealth
browser = launch(headless=False, proxy="http://your-residential-proxy:port")
page = browser.new_page()
page.goto("https://heavily-protected-site.com")  # passes DataDome, etc.
browser.close()
```

--------------------------------

### Manage CloakBrowser via CLI

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Use these commands to handle authentication, binary installation, and diagnostics from the terminal.

```bash
python -m cloakbrowser login        # Get a free key via GitHub, or save a paid key
python -m cloakbrowser logout        # Remove the saved key (revert to the free binary)
python -m cloakbrowser install      # Download binary with progress output
python -m cloakbrowser info         # Diagnostics: binary that will launch, license tier, env checks
python -m cloakbrowser update       # Check for and download newer binary
python -m cloakbrowser clear-cache  # Remove cached binaries
```

--------------------------------

### Usage example for clear_cache

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Clears the local cache to force a fresh download on the next launch.

```python
from cloakbrowser import clear_cache

# Force re-download on next launch
clear_cache()
```

--------------------------------

### Update CloakBrowser packages

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Ensure the latest version is installed across different environments.

```bash
pip install -U cloakbrowser    # Python
npm install cloakbrowser@latest # JavaScript
docker pull cloakhq/cloakbrowser:latest  # Docker
```

--------------------------------

### Install Linux System Dependencies

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Required system libraries and fonts for running CloakBrowser on Linux distributions.

```bash
sudo apt install -y \
  libxss1 libappindicator1 libindicator7 \
  fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
  fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
```

--------------------------------

### Build Custom Image from Pip

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Install the CloakBrowser binary during the Docker build process using pip.

```dockerfile
FROM python:3.12-slim
RUN pip install cloakbrowser && python -m cloakbrowser install
COPY your_script.py /app/
CMD ["python", "/app/your_script.py"]
```

--------------------------------

### Launch Playwright browsers and contexts

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Use these methods to initialize browser instances, persistent contexts, or combined browser-context setups with custom configurations.

```javascript
import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';

// Basic
const browser = await launch();

// Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
const browser = await launch({ licenseKey: 'cb_xxxxxxxx' });

// With options
const browser = await launch({
  headless: false,
  proxy: 'http://user:pass@proxy:8080',
  args: ['--fingerprint=12345'],
  timezone: 'America/New_York',
  locale: 'en-US',
  humanize: true,
});

// Convenience: browser + context in one call
const context = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezone: 'America/New_York',
});
const page = await context.newPage();

// Persistent profile — cookies/localStorage survive restarts, avoids incognito detection
const ctx = await launchPersistentContext({
  userDataDir: './chrome-profile',
  headless: false,
  proxy: 'http://user:pass@proxy:8080',
});
```

--------------------------------

### GET /json/version

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Retrieves the Chrome DevTools Protocol discovery document, including the WebSocket debugger URL.

```APIDOC
## GET /json/version

### Description
Fetches the browser version and the WebSocket debugger URL for CDP connections.

### Method
GET

### Endpoint
/json/version

### Parameters
#### Query Parameters
- **fingerprint** (string) - Optional - The fingerprint seed to scope the WebSocket URL to a specific browser instance.
```

--------------------------------

### launch(options)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Initializes a browser instance with human behavior simulation enabled.

```APIDOC
## launch(options)

### Description
Launches a browser instance with human-like interaction capabilities enabled. This replaces standard automation calls with realistic mouse movements, typing patterns, and scrolling.

### Parameters
- **humanize** (boolean) - Optional - Enables human behavior simulation.
- **human_preset** (string) - Optional - Sets the behavior profile (e.g., 'default', 'careful').
- **human_config** (object) - Optional - Custom configuration for interaction parameters.

### Configuration Fields
- **mistype_chance** (number) - Probability of typos.
- **typing_delay** (number) - Delay in milliseconds per character.
- **idle_between_actions** (boolean) - Enables micro-movements between actions.
- **idle_between_duration** (array) - Range of idle duration in seconds.

### Usage Example
```python
browser = launch(humanize=True, human_preset="careful", human_config={
    "mistype_chance": 0.05,
    "typing_delay": 100
})
```
```

--------------------------------

### launch(headless=False, proxy=None, geoip=True, humanize=True, args=None, license_key=None)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/README.md

Launches a new browser instance with specified configuration, including proxy settings, fingerprinting options, and license keys.

```APIDOC
## launch

### Description
Launches a new browser instance. Supports configuration for headless mode, proxy integration, geo-location matching, and human-like behavior simulation.

### Parameters
- **headless** (bool) - Optional - Whether to run the browser in headless mode.
- **proxy** (str) - Optional - Proxy URL for the browser session.
- **geoip** (bool) - Optional - Whether to match timezone to the proxy location.
- **humanize** (bool) - Optional - Whether to enable human-like behavior simulation.
- **args** (list) - Optional - List of additional Chromium command-line arguments.
- **license_key** (str) - Optional - License key for authentication.
```

--------------------------------

### Launch CloakBrowser in Python

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/README.md

Demonstrates basic browser initialization and configuration with optional proxy and humanization settings.

```python
from cloakbrowser import launch

# Basic — headless, stealth fingerprint, no proxy
browser = launch()
page = browser.new_page()
page.goto("https://example.com")
browser.close()

# With options
browser = launch(
    headless=False,
    proxy="http://user:pass@proxy:8080",
    geoip=True,
    humanize=True,
    license_key="cb_xxxxxxxx",  # Pro (optional)
)
```

--------------------------------

### Manage CloakBrowser Binary via CLI

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Commands for installing, inspecting, updating, and clearing the cached browser binary when working from a repository clone.

```bash
dotnet run --project src/CloakBrowser.Cli -- install      # download the binary
dotnet run --project src/CloakBrowser.Cli -- info         # version / path / platform
dotnet run --project src/CloakBrowser.Cli -- update       # check + download newer
dotnet run --project src/CloakBrowser.Cli -- clear-cache  # remove cached binaries
```

--------------------------------

### launch(options)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Launches a new browser instance with optional proxy and geolocation settings.

```APIDOC
## launch(options)

### Description
Launches a browser instance. Supports automatic timezone and locale detection based on proxy IP when `geoip` is enabled.

### Parameters
- **proxy** (string) - Optional - Proxy URL (e.g., 'http://proxy:8080')
- **geoip** (boolean) - Optional - Enable auto-detection of timezone and locale from proxy IP
- **timezone** (string) - Optional - Explicit timezone string (overrides auto-detection)
- **locale** (string) - Optional - Explicit locale string (overrides auto-detection)
```

--------------------------------

### Launch browser instance with launch()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Configures and initializes a browser instance with various stealth, proxy, and fingerprinting options.

```python
from cloakbrowser import launch

# Basic — headless, default stealth config
browser = launch()

# Headed mode (see the browser window)
browser = launch(headless=False)

# Latest binary — pass a key (free via `cloakbrowser login`, or paid) or set CLOAKBROWSER_LICENSE_KEY
browser = launch(license_key="cb_xxxxxxxx")

# With proxy (HTTP or SOCKS5)
browser = launch(proxy="http://user:pass@proxy:8080")
browser = launch(proxy="socks5://user:pass@proxy:1080")

# With proxy dict (bypass, separate auth fields)
browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com", "username": "user", "password": "pass"})

# With extra Chrome args
browser = launch(args=["--disable-gpu"])

# With timezone and locale (sets binary flags — no detectable CDP emulation)
browser = launch(timezone="America/New_York", locale="en-US")

# Auto-detect timezone/locale from proxy IP (requires: pip install cloakbrowser[geoip])
# Also auto-injects --fingerprint-webrtc-ip to prevent WebRTC IP leaks (no extra cost)
# Note: makes HTTP calls through your proxy to resolve exit IP (ipify.org, checkip.amazonaws.com)
browser = launch(proxy="http://proxy:8080", geoip=True)

# Explicit timezone/locale always win over auto-detection
browser = launch(proxy="http://proxy:8080", geoip=True, timezone="Europe/London")

# WebRTC IP spoofing only (no geoip dep needed — resolves exit IP via HTTP call through proxy)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=auto"])

# Explicit WebRTC IP (no network call)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=1.2.3.4"])

# Human-like mouse, keyboard, and scroll behavior
browser = launch(humanize=True)

# With slower, more deliberate movements
browser = launch(humanize=True, human_preset="careful")

# Without default stealth args (bring your own fingerprint flags)
browser = launch(stealth_args=False, args=["--fingerprint=12345"])
```

--------------------------------

### Manage CloakBrowser via Python

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Use these functions to programmatically check binary status, clear cache, or ensure the binary is installed during application runtime or build processes.

```python
from cloakbrowser import binary_info, clear_cache, ensure_binary

# Check binary installation status
print(binary_info())
# {'version': '146.0.7680.177.5', 'platform': 'linux-x64', 'installed': True, ...}

# Force re-download
clear_cache()

# Pre-download binary (e.g., during Docker build)
ensure_binary()
```

--------------------------------

### Initialize Browser with License Key

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Pass the license key directly to the launch function in Python or JavaScript.

```python
from cloakbrowser import launch

browser = launch(license_key="cb_xxxxxxxx")
```

```javascript
import { launch } from 'cloakbrowser';

const browser = await launch({ licenseKey: 'cb_xxxxxxxx' });
```

--------------------------------

### Copy Widevine CDM from Chrome

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Manually copies the Widevine CDM from an existing Google Chrome installation to the CloakBrowser directory.

```bash
cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
```

--------------------------------

### Configure ProxySettings for launch

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/types.md

Demonstrates passing a proxy dictionary to the launch function.

```python
proxy_dict = {
    "server": "http://proxy:8080",
    "bypass": ".google.com,.internal.local",
    "username": "user",
    "password": "pass",
}
browser = launch(proxy=proxy_dict)
```

--------------------------------

### CloakLauncher.LaunchContextAsync

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Launches a browser-owned context with specific emulation settings.

```APIDOC
## LaunchContextAsync(LaunchContextOptions)

### Description
Launches a browser-owned context with emulation capabilities such as locale, timezone, and viewport settings.

### Parameters
- **options** (LaunchContextOptions) - Required - Configuration for the context, including Locale, Timezone, Viewport, and ColorScheme.
```

--------------------------------

### Build and test the solution

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Commands to compile and verify the CloakBrowser solution.

```bash
cd dotnet
dotnet build CloakBrowser.sln     # 0 warnings, 0 errors
dotnet test  CloakBrowser.sln     # all green
```

--------------------------------

### checkForUpdate()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Checks the server for available browser updates without downloading or installing.

```APIDOC
## checkForUpdate(licenseKey?: string, releaseChannel?: string)

### Description
Queries the server to check if a newer version of the browser is available. Results are cached for 1 hour.

### Parameters
- **licenseKey** (string) - Optional - The license key for authentication.
- **releaseChannel** (string) - Optional - The release channel to check.

### Returns
- **Promise<string | null>** - The new version string if an update is available, otherwise null.
```

--------------------------------

### Handle CloakBrowserLicenseError

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/types.md

Exception class for license-related failures and an example of how to catch it during browser launch.

```python
class CloakBrowserLicenseError(RuntimeError):
    """The Pro binary refused to run for a license reason."""
    pass
```

```python
from cloakbrowser import launch, CloakBrowserLicenseError

try:
    browser = launch(license_key="cb_invalid")
except CloakBrowserLicenseError as e:
    print(f"License error: {e}")
```

--------------------------------

### launch()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Initializes a stealth Chromium browser instance with configurable settings for headless mode, proxies, human-like behavior, and fingerprinting.

```APIDOC
## launch(headless=True, proxy=None, args=None, ...)

### Description
Launches a stealth Chromium browser instance in synchronous mode using Playwright. The returned browser object is pre-configured with stealth patches and optional human-like interaction capabilities.

### Parameters
- **headless** (bool) - Optional - Run in headless mode (default: True).
- **proxy** (str | ProxySettings) - Optional - Proxy URL or configuration dictionary.
- **args** (list[str]) - Optional - Additional Chromium CLI arguments.
- **stealth_args** (bool) - Optional - Include default stealth fingerprint flags (default: True).
- **timezone** (str) - Optional - IANA timezone string.
- **locale** (str) - Optional - BCP 47 locale string.
- **geoip** (bool) - Optional - Auto-detect timezone/locale from proxy IP (default: False).
- **humanize** (bool) - Optional - Enable human-like mouse/keyboard behavior (default: False).
- **human_preset** (HumanPreset) - Optional - Preset for human behavior: 'default' or 'careful'.
- **human_config** (HumanConfigOverrides) - Optional - Custom configuration for human behavior.
- **extension_paths** (list[str]) - Optional - List of paths to Chrome extensions.
- **license_key** (str) - Optional - Pro license key.
- **browser_version** (str) - Optional - Specific Chromium version to use.
- **release_channel** (str) - Optional - Binary release channel: 'stable' or 'preview'.
- ****kwargs** (Any) - Optional - Additional arguments forwarded to Playwright's launch method.

### Return Value
- **Browser** - A standard Playwright Browser object.

### Raises
- **CloakBrowserLicenseError** - If the license key is invalid or expired.
- **BinaryVerificationError** - If the browser binary fails verification.
- **RuntimeError** - If the platform is unsupported or download fails.
```

--------------------------------

### Configure CloakBrowser for Framework Integration

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Demonstrates two primary methods for integrating CloakBrowser: launching the binary directly or connecting via CDP.

```python
# Option 1: Framework launches our binary directly (Selenium, Stagehand, UC)
from cloakbrowser.download import ensure_binary
from cloakbrowser.config import get_default_stealth_args
binary_path = ensure_binary()          # auto-downloads if needed
stealth_args = get_default_stealth_args()  # all fingerprint flags

# Option 2: CloakBrowser launches first, framework connects via CDP (browser-use, Crawl4AI, Scrapling)
from cloakbrowser import launch_async
browser = await launch_async(args=["--remote-debugging-port=9242"])
# Connect your framework to http://127.0.0.1:9242 — all stealth flags are set
# Note: humanize requires the wrapper (see below)
```

--------------------------------

### CloakLauncher.LaunchAsync

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Launches a new browser instance and returns a handle for managing browser operations.

```APIDOC
## LaunchAsync(LaunchOptions)

### Description
Launches a browser instance. Returns a `CloakBrowserHandle` which supports `NewPageAsync`, `NewContextAsync`, `NewHumanPageAsync`, and `RawBrowser` operations.

### Parameters
- **options** (LaunchOptions) - Required - Configuration options for the browser launch.
```

--------------------------------

### Resolve and Merge HumanConfig

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Demonstrates how to create a configuration using a preset with overrides and how to merge new settings into an existing configuration instance.

```csharp
// preset + overrides
var cfg = HumanConfigFactory.Resolve(
    HumanPreset.Careful,
    new Dictionary<string, object> { ["typing_delay"] = 120.0, ["key_hold"] = (40.0, 90.0) });

// merge onto an existing config (never mutates the base; returns a new instance)
var faster = cfg.With(new Dictionary<string, object> { ["TypingDelay"] = 30.0 });
```

--------------------------------

### Define binary_info function signature

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Signature for the function that retrieves metadata about the current binary installation.

```python
from cloakbrowser import binary_info

def binary_info() -> dict[str, Any]
```

--------------------------------

### Launch Asynchronous Browser Context

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Demonstrates the asynchronous initialization of a browser context and saving state to a JSON file.

```python
import asyncio
from cloakbrowser import launch_context_async

async def main():
    ctx = await launch_context_async(storage_state="state.json")
    page = await ctx.new_page()
    await page.goto("https://example.com")
    await ctx.storage_state(path="state.json")
    await ctx.close()

asyncio.run(main())
```

--------------------------------

### Catch BinaryVerificationError

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/errors.md

Example of handling binary verification failures, which indicate potential security issues.

```python
from cloakbrowser import ensure_binary, BinaryVerificationError

try:
    path = ensure_binary()
except BinaryVerificationError as e:
    print(f"Binary verification failed: {e}")
    # This is a security issue, not a transient failure; do not retry with different mirrors.
except Exception as e:
    print(f"Download failed: {e}")  # network error, retry
```

--------------------------------

### Opt into Preview Release Channel

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Enable the preview release channel to access the newest available builds.

```csharp
await using var browser = await CloakLauncher.LaunchAsync(new LaunchOptions
{
    LicenseKey = "cb_xxxxxxxx",
    ReleaseChannel = "preview",
});
```

--------------------------------

### Launch browser context with launch_context()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Creates a browser and context simultaneously with specific configuration or session state.

```python
from cloakbrowser import launch_context

context = launch_context(
    user_agent="Custom UA",
    viewport={"width": 1920, "height": 1080},
    locale="en-US",
    timezone="America/New_York",
)
page = context.new_page()
page.goto("https://protected-site.com")
context.close()
```

```python
from cloakbrowser import launch_context

# Restore a saved session (cookies, localStorage) from a JSON file
context = launch_context(storage_state="state.json")
page = context.new_page()
page.goto("https://example.com")
# Save state back for next run
context.storage_state(path="state.json")
context.close()
```

--------------------------------

### Set custom binary path

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Point the launcher to a local browser binary.

```bash
export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
```

--------------------------------

### GET https://cloakbrowser.dev/api/license/session/count

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Retrieves the current active seat count for a specific license key.

```APIDOC
## GET https://cloakbrowser.dev/api/license/session/count

### Description
Returns the number of active sessions and the total seat limit for the provided license key.

### Method
GET

### Endpoint
https://cloakbrowser.dev/api/license/session/count

### Parameters
#### Query Parameters
- **license_key** (string) - Required - The license key to check.

### Response
#### Success Response (200)
- **active** (integer) - Number of currently active sessions.
- **limit** (integer) - Maximum allowed sessions for the license.

#### Response Example
{
  "active": 2,
  "limit": 5
}
```

--------------------------------

### launch_context()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Creates a browser context with specific browser settings.

```APIDOC
## launch_context(user_agent=None, viewport=None, locale=None, timezone=None, **kwargs)

### Description
Convenience function that creates a browser and context in one call. Extra kwargs are forwarded to Playwright's `browser.new_context()`.
```

--------------------------------

### Launch CloakBrowser

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Initializes a browser instance using CloakLauncher with headless mode enabled.

```csharp
using CloakBrowser;

await using var browser = await CloakLauncher.LaunchAsync(new LaunchOptions
{
    Headless = true,
});

var page = await browser.NewPageAsync();
await page.GotoAsync("https://bot.incolumitas.com/");
Console.WriteLine(await page.TitleAsync());
```

--------------------------------

### Configure Custom Mirror

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Environment variable configuration to point to a custom binary mirror.

```bash
export CLOAKBROWSER_DOWNLOAD_URL=https://your-mirror.example.com

# Binary downloads from:
# https://your-mirror.example.com/chromium-v146.0.7680.177.5/cloakbrowser-linux-x64.tar.gz
```

--------------------------------

### launchContext(options)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Launches a browser context with specific user agent and viewport settings.

```APIDOC
## launchContext(options)

### Description
Initializes a browser context with custom environment settings.

### Parameters
- **options** (Object) - Configuration object:
  - **userAgent** (string) - Custom user agent string.
  - **viewport** (Object) - Viewport dimensions (width, height).
  - **locale** (string) - Locale string.
  - **timezone** (string) - Timezone string.
```

--------------------------------

### Launch Browser with Custom Flags

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Demonstrates how to pass specific fingerprinting and GPU flags to the browser launch function.

```python
from cloakbrowser import launch

browser = launch(
    args=[
        "--fingerprint=42069",                     # persistent seed
        "--fingerprint-gpu-vendor=NVIDIA Corporation",
        "--fingerprint-gpu-renderer=NVIDIA GeForce RTX 3080",
        "--disable-gpu",
    ],
    proxy="http://proxy:8080",
    timezone="America/Los_Angeles",
    humanize=True,
)
```

--------------------------------

### GET https://cloakbrowser.dev/api/download/version

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/license-management.md

Resolves the latest available Pro binary version for a specific platform and channel.

```APIDOC
## GET https://cloakbrowser.dev/api/download/version

### Description
Fetches the latest version information for the Pro binary based on the provided license and platform.

### Method
GET

### Endpoint
https://cloakbrowser.dev/api/download/version

### Parameters
#### Query Parameters
- **license_key** (string) - Required - The license key (required for Pro).
- **platform** (string) - Required - The target platform (e.g., linux-x64).
- **channel** (string) - Optional - The release channel (stable or preview).

### Response
#### Success Response (200)
- **version** (string) - The latest version string.
- **requested_channel** (string) - The channel requested.
- **resolved_channel** (string) - The channel resolved.
- **fallback** (boolean) - Whether a fallback version was used.

#### Response Example
{
  "version": "151.0.7922.108.2",
  "requested_channel": "stable",
  "resolved_channel": "stable",
  "fallback": false
}
```

--------------------------------

### Configure Preview release channel

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Opt into the preview release channel for specific launches or globally via environment variables.

```python
browser = launch(license_key="cb_xxxxxxxx", release_channel="preview")
```

```javascript
const browser = await launch({ licenseKey: 'cb_xxxxxxxx', releaseChannel: 'preview' });
```

```csharp
await using var browser = await CloakLauncher.LaunchAsync(new LaunchOptions
{
    LicenseKey = "cb_xxxxxxxx",
    ReleaseChannel = "preview",
});
```

```bash
export CLOAKBROWSER_RELEASE_CHANNEL=preview
```

--------------------------------

### launch()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Launches a new browser instance using the Playwright wrapper.

```APIDOC
## launch(options)

### Description
Launches a new browser instance with stealth capabilities.

### Parameters
- **options** (object) - Optional - Configuration object including licenseKey, headless, proxy, args, timezone, locale, humanize, stealthArgs, and geoip.
```

--------------------------------

### Configure Preview Release Channel

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Opt into the preview release channel during browser launch to access the newest builds.

```javascript
const browser = await launch({
  licenseKey: 'cb_xxxxxxxx',
  releaseChannel: 'preview',
});
```

--------------------------------

### Launch an emulated browser context

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Initializes a browser context with specific locale, timezone, viewport, and color scheme settings.

```csharp
// emulated context
await using var ctx = await CloakLauncher.LaunchContextAsync(new LaunchContextOptions
{
    Locale      = "en-US",
    Timezone    = "America/New_York",
    Viewport    = (1280, 800),
    ColorScheme = "dark",
});
var page = await ctx.NewPageAsync();
```

--------------------------------

### Execute CLI Commands

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/README.md

Manage licenses, binaries, and browser diagnostics via the command line or npx.

```bash
# License management
cloakbrowser login              # Get/store free or Pro key
cloakbrowser logout             # Remove stored key

# Binary management
cloakbrowser install            # Download binary
cloakbrowser update             # Check and download updates
cloakbrowser clear-cache        # Remove cached binaries
cloakbrowser info               # Show diagnostics

# Same commands available in Node.js
npx cloakbrowser install
```

--------------------------------

### Sideload Widevine CDM

Source: https://github.com/cloakhq/cloakbrowser/blob/main/js/README.md

Copy the WidevineCdm directory from a Chrome installation to the CloakBrowser cache directory to enable DRM support.

```bash
cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
```

--------------------------------

### Launch with Proxy and Humanization

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Configures the browser with a proxy, enables geo-based localization, and activates human-like interaction patterns.

```python
from cloakbrowser import launch

browser = launch(
    proxy="http://user:pass@residential-proxy:8080",
    geoip=True,
    humanize=True,
    headless=False,
)
page = browser.new_page()
page.goto("https://protected-site.com")
page.locator("#email").fill("user@example.com")  # human-like timing
browser.close()
```

--------------------------------

### Pin Browser Versions

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/binary-management.md

Demonstrates how to pin specific browser versions for Free and Pro tiers using the launch function.

```python
# Free tier — pin to a public release
browser = launch(browser_version="146.0.7680.177.5")

# Pro tier — pin to a Pro release
browser = launch(license_key="cb_xxxxxxxx", browser_version="148.0.7778.215.2")
```

--------------------------------

### Manage License Keys via CLI and Environment

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Methods for authenticating the browser session using interactive prompts, direct key injection, environment variables, or programmatic initialization.

```bash
# Interactive CLI prompt
cloakbrowser login

# Direct save
cloakbrowser login cb_xxxxxxxx

# Environment variable (takes precedence)
export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

# In code
browser = launch(license_key="cb_xxxxxxxx")
```

--------------------------------

### Manage License with CLI

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/configuration.md

Use login to store a license key interactively or directly, and logout to remove it.

```bash
cloakbrowser login              # Interactive prompt (GitHub sign-in or paste key)
cloakbrowser login cb_xxxxxxxx  # Direct save
```

```bash
cloakbrowser logout
```

--------------------------------

### Launch CloakBrowser in JavaScript

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/README.md

Demonstrates asynchronous browser initialization and page navigation using the JavaScript API.

```javascript
import { launch } from 'cloakbrowser';

const browser = await launch({
  headless: false,
  proxy: 'http://user:pass@proxy:8080',
  geoip: true,
  humanize: true,
  licenseKey: 'cb_xxxxxxxx',  // Pro (optional)
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();
```

--------------------------------

### Local Lambda Invocation Test

Source: https://github.com/cloakhq/cloakbrowser/blob/main/examples/integrations/aws_lambda/INSTRUCTIONS.md

Starts a Docker container for local testing and then sends a curl request to the Lambda invocation endpoint. This simulates a Lambda invocation without deploying to AWS.

```bash
docker run --rm -p 9000:8080 cloakbrowser-lambda:arm64
```

```bash
curl -sS -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" \
  -d '{"url":"https://example.com"}'
```

--------------------------------

### Build Image from Source

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Build a local Docker image using the provided Dockerfile.

```bash
docker build -t cloakbrowser .
```

--------------------------------

### launch_context()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Synchronous convenience function that launches a browser and creates a context in one call.

```APIDOC
## launch_context()

### Description
Convenience function that launches a browser and creates a context in one call, returning the context with sensible defaults.

### Signature
```python
def launch_context(
    headless: bool = True,
    proxy: str | ProxySettings | None = None,
    args: list[str] | None = None,
    stealth_args: bool = True,
    user_agent: str | None = None,
    viewport: Any = _VIEWPORT_UNSET,
    locale: str | None = None,
    timezone: str | None = None,
    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
    geoip: bool = False,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
    extension_paths: list[str] | None = None,
    license_key: str | None = None,
    browser_version: str | None = None,
    release_channel: str | None = None,
    **kwargs: Any,
) -> BrowserContext
```

### Example
```python
from cloakbrowser import launch_context

context = launch_context(
    user_agent="Custom UA",
    viewport={"width": 1920, "height": 1080},
    storage_state="state.json",
)
page = context.new_page()
page.goto("https://example.com")
context.storage_state(path="state.json")
context.close()
```
```

--------------------------------

### launch_async()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/README.md

Asynchronous version of the launch method.

```APIDOC
## launch_async(**kwargs)

### Description
Asynchronously launches a browser instance. Accepts the same arguments as `launch()`.
```

--------------------------------

### CloakLauncher.LaunchPersistentContextAsync

Source: https://github.com/cloakhq/cloakbrowser/blob/main/dotnet/README.md

Launches a persistent browser context that reuses a profile directory.

```APIDOC
## LaunchPersistentContextAsync(string, LaunchContextOptions)

### Description
Launches a context that reuses a profile directory, allowing cookies and localStorage to persist across sessions.

### Parameters
- **userDataDir** (string) - Required - The path to the directory where profile data is stored.
- **options** (LaunchContextOptions) - Required - Configuration options for the persistent context.
```

--------------------------------

### Launch Browser Context

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Creates a browser context directly with custom configuration. The returned context automatically manages the browser lifecycle.

```python
from cloakbrowser import launch_context

context = launch_context(
    user_agent="Custom UA",
    viewport={"width": 1920, "height": 1080},
    storage_state="state.json",  # restore cookies/localStorage from file
)
page = context.new_page()
page.goto("https://example.com")
context.storage_state(path="state.json")  # save for next run
context.close()
```

--------------------------------

### launch() (Puppeteer)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/launch-functions.md

Launches a Puppeteer-compatible browser instance using CloakBrowser settings.

```APIDOC
## launch(options)

### Description
Launches a browser instance compatible with Puppeteer. Returns a Puppeteer Browser object.

### Signature
`async launch(options: object) -> Browser`

### Parameters
- **options** (object) - Required - Configuration options identical to the Playwright version.
```