### JavaScript: binaryInfo

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Get information about the binary installation, including version, platform, and installation status.

```APIDOC
## JavaScript: binaryInfo

### Description
Get information about the binary installation.

### Signature
```typescript
function binaryInfo(): BinaryInfo
```

### Type Definition
```typescript
interface BinaryInfo {
  version: string;      // e.g., '146.0.7680.177.5'
  platform: string;     // e.g., 'linux-x64'
  installed: boolean;
  path?: string;
}
```

### Example
```typescript
import { binaryInfo } from 'cloakbrowser';

const info = binaryInfo();
console.log(`Version: ${info.version}`);
console.log(`Installed: ${info.installed}`);
```
```

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

### CLI Commands: install

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Installs the browser binary with progress output, useful for automated build environments like Docker.

```APIDOC
## CLI Command: install

### Description
Installs the browser binary with progress output, useful for automated build environments like Docker.

### Usage
```bash
python -m cloakbrowser install
# or
npx cloakbrowser install
```
```

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

### Python: Get Binary Information

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Retrieves information about the downloaded binary and its installation status, including version, platform, installation state, and path.

```python
from cloakbrowser import binary_info

info = binary_info()
print(f"Installed: {info['installed']}")
print(f"Version: {info['version']}")
print(f"Platform: {info['platform']}")
print(f"Path: {info['path']}")
```

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

### Python: binary_info

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Get information about the downloaded binary and installation status. This includes version, platform, installation status, and path.

```APIDOC
## Python: binary_info

### Description
Get information about the downloaded binary and installation status.

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

### Returns
Dictionary with keys:
- `version` (str): Chromium version (e.g., '146.0.7680.177.5')
- `platform` (str): Platform tag (e.g., 'linux-x64', 'darwin-arm64', 'windows-x64')
- `installed` (bool): Whether binary is currently downloaded
- `path` (str): Absolute path to binary (or None if not installed)

### Example
```python
from cloakbrowser import binary_info

info = binary_info()
print(f"Installed: {info['installed']}")
print(f"Version: {info['version']}")
print(f"Platform: {info['platform']}")
print(f"Path: {info['path']}")
```
```

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

### JavaScript: Get Binary Information

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Retrieves information about the binary installation, including version, platform, and whether it is installed. The path is optional.

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

const info = binaryInfo();
console.log(`Version: ${info.version}`);
console.log(`Installed: ${info.installed}`);
```

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

### Launch Browser with GeoIP, Humanize, and Headed Mode (Python)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/geoip.md

Launch a browser with GeoIP enabled for automatic timezone/locale detection, `humanize=True` for more natural behavior, and `headless=False` to run in headed mode. This example demonstrates a comprehensive setup for realistic browsing scenarios.

```python
from cloakbrowser import launch

browser = launch(
    proxy="http://user:pass@residential-proxy:8080",
    geoip=True,              # Auto-detect timezone/locale
    headless=False,          # Headed mode
    humanize=True,           # Human-like behavior
)
page = browser.new_page()
page.goto("https://anti-bot-test.com")
browser.close()
```

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

### ProxySettings Usage Example

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

Demonstrates how to launch the browser with a configured proxy. Ensure the ProxySettings dictionary includes at least the 'server' field.

```python
from cloakbrowser import launch, ProxySettings

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

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

### CLI Commands: info

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Displays the current installation status and version information for the browser binary.

```APIDOC
## CLI Command: info

### Description
Displays the current installation status and version information for the browser binary.

### Usage
```bash
python -m cloakbrowser info
# or
npx cloakbrowser info
```

### Output Example
```
CloakBrowser v0.3.31
Chromium: 146.0.7680.177.5 (linux-x64)
Installed: Yes
Path: /home/user/.cloakbrowser/chromium-146.0.7680.177.5/chrome
```
```

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

### Install CloakBrowser Binary (CLI)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Installs the CloakBrowser binary. This command is useful for pre-downloading the binary, especially in automated build environments like Docker.

```bash
python -m cloakbrowser install
# or
npx cloakbrowser install
```

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

### Launch CloakBrowser and Load a Page (Python)

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

Basic example of launching CloakBrowser and navigating to a URL using Python. Ensure the CloakBrowser binary is downloaded.

```python
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
```

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

### Launch Browser with Default Stealth

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

Launches a browser instance with default headless and stealth configurations. This is the most basic way to start.

```python
from cloakbrowser import launch

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

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

### Display CloakBrowser Installation Info (CLI)

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Shows the current CloakBrowser version, the bundled Chromium version, installation status, and the binary path. This helps verify the installation and identify the exact Chromium version in use.

```bash
python -m cloakbrowser info
# or
npx cloakbrowser info
```

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

### Check Binary Installation Status

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

Prints information about the CloakBrowser binary installation, including version, platform, and whether it is installed. This utility function is useful for verifying setup.

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

# Check binary installation status
print(binary_info())
```

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

### Install CloakBrowser with Playwright

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

Install CloakBrowser and Playwright core dependencies.

```bash
npm install cloakbrowser playwright-core
```

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

### Get CloakBrowser Info

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

Displays information about the installed CloakBrowser binary, including its version, path, and platform. This is a CLI command for checking installation status.

```bash
python -m cloakbrowser info
```

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

### Install CloakBrowser with GeoIP support

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

Install the Python package with optional GeoIP support for auto-detecting timezone and locale from proxy IP.

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

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

### Install Playwright system dependencies

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

You do not need `playwright install chromium`. CloakBrowser downloads its own binary. Only install Playwright's system dependencies.

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

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

### Start CDP Server in Docker

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

Start a persistent CloakBrowser CDP server in Docker. This allows remote connections via Chrome DevTools Protocol.

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

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

### Launch Browser with Puppeteer

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/javascript-launch.md

Demonstrates how to import and use the `launch` function from `cloakbrowser/puppeteer` to start a browser instance. The signature and options are identical to Playwright.

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

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

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

### Install CloakBrowser Binary in Docker for AWS Lambda

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

This Dockerfile command installs the CloakBrowser package and its binary, preparing it for use in an AWS Lambda environment.

```dockerfile
RUN pip install cloakbrowser && python -m cloakbrowser install
```

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

### Start CDP Server with Extra Flags

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

Start the CloakBrowser CDP server with additional flags to configure proxy, headless mode, or idle timeout.

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

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

### buildLaunchOptions

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/javascript-launch.md

Builds Playwright launch options without starting Chromium. This is useful for integrating CloakBrowser with custom Playwright builds.

```APIDOC
## buildLaunchOptions

### Description
Builds Playwright launch options without starting Chromium. Useful for integrating CloakBrowser with custom Playwright builds.

### Method
`buildLaunchOptions(options?: LaunchOptions)`

### Parameters
#### Query Parameters
- **proxy** (string) - Optional - The proxy server to use for the browser instance.
- **geoip** (boolean) - Optional - Whether to enable GeoIP spoofing.

### Request Example
```javascript
import { buildLaunchOptions } from 'cloakbrowser';

const launchOptions = await buildLaunchOptions({
  proxy: 'http://proxy:8080',
  geoip: true,
});
// launchOptions can be passed to chromium.launch(launchOptions)
```

### Response
Returns an object containing Playwright launch options.
```

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

### Basic Python Usage with CloakBrowser

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

Launch CloakBrowser and navigate to a webpage using the Python API. This is a simple example demonstrating basic browser automation.

```python
from cloakbrowser import launch

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

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

### Run CloakBrowser Manager with Docker

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

Start the self-hosted Browser Profile Manager using Docker. It runs on port 8080 and uses a volume for profile data.

```bash
docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager
```

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

### Launch Persistent Context with Custom Storage Quota

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

Use this strategy when targeting services like BrowserScan that penalize small storage quotas. This example raises the quota to 5000MB.

```python
ctx = launch_persistent_context(
    "./profile",
    args=["--fingerprint-storage-quota=5000"]
)
```

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

### Run CloakBrowser as a Service for Parallel Scraping

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

Start CloakBrowser as a standalone service using `cloakserve`. Multiple Docker containers can then connect to this single CDP server for parallel scraping.

```bash
docker run -d cloakhq/cloakbrowser cloakserve
# Connect multiple clients to single CDP server
```

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

### Manage CloakBrowser Binary (JS)

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

Provides utility functions for managing the CloakBrowser binary, including pre-downloading, checking installation status, and clearing the cache for a re-download.

```javascript
import { ensureBinary, clearCache, binaryInfo } from 'cloakbrowser';

// Pre-download binary (e.g., during Docker build)
await ensureBinary();

// Check installation status
console.log(binaryInfo());

// Force re-download
clearCache();
```

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

### launch_persistent_context

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-persistent-context.md

Launches a persistent browser context using a specified profile directory. This allows for state to be saved across sessions. Examples show default usage, adjusting storage quota for fingerprinting, and sideloading Widevine CDM.

```APIDOC
## launch_persistent_context

### Description
Launches a persistent browser context using a specified profile directory. This allows for state to be saved across sessions. Examples show default usage, adjusting storage quota for fingerprinting, and sideloading Widevine CDM.

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

### Parameters

- **user_data_dir** (str | os.PathLike) - Path to the user data directory for the browser profile.
- **headless** (bool, optional) - Whether to run the browser in headless mode. Defaults to True.
- **proxy** (str | ProxySettings | None, optional) - Proxy configuration.
- **args** (list[str] | None, optional) - Additional command-line arguments to pass to the browser.
- **stealth_args** (bool, optional) - Whether to apply stealth arguments. Defaults to True.
- **user_agent** (str | None, optional) - Custom user agent string.
- **viewport** (dict | None, optional) - Viewport size for the browser window.
- **locale** (str | None, optional) - Browser locale.
- **timezone** (str | None, optional) - Browser timezone.
- **color_scheme** (Literal["light", "dark", "no-preference"] | None, optional) - Color scheme preference.
- **geoip** (bool, optional) - Whether to enable GeoIP spoofing. Defaults to False.
- **backend** (str | None, optional) - Specifies the backend to use.
- **humanize** (bool, optional) - Whether to apply human-like browser behavior. Defaults to False.
- **human_preset** (HumanPreset, optional) - Preset for human-like behavior. Defaults to "default".
- **human_config** (HumanConfigOverrides | None, optional) - Overrides for human-like behavior configuration.
- **extension_paths** (list[str] | None, optional) - Paths to browser extensions to load. Note: Extensions only work with persistent contexts.

### Return Value

**Type:** `BrowserContext` (Playwright BrowserContext)

A persistent context object that can be used to manage browser sessions and pages.

### Example

```python
from cloakbrowser import launch_persistent_context

# Default usage
ctx = launch_persistent_context("./my-profile")
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()

# Adjusting storage quota for fingerprinting
ctx = launch_persistent_context(
    "./my-profile",
    args=["--fingerprint-storage-quota=5000"],  # MB
)
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()

# Sideloading Widevine CDM for DRM
# (Requires manual setup of WidevineCdm in the profile directory)
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://netflix.com")
ctx.close()
```

### Notes

- **Profile creation:** The profile directory is created automatically on first run. You do not need to pre-create it.
- **Profile isolation:** Each `user_data_dir` represents a separate browser profile with its own identity, cookies, extensions, and settings.
- **SingletonLock:** Chromium prevents multiple processes from using the same profile simultaneously. Attempting to launch a second context with the same `user_data_dir` will fail if the first one is still running.
- **Extension loading:** Extensions only work with persistent contexts. Attempting to use `extension_paths` with `launch()` or `launch_context()` will fail.
- **Widevine/DRM:** The wrapper auto-seeds the Widevine CDM hint file (Linux only) on first launch if the CDM is present. On Windows/macOS, seeding is a no-op (Chromium's CDM hint mechanism is Linux/ChromeOS-specific).
- **Storage quota tradeoff:**
  - Default (normalized ~500MB): **Passes FingerprintJS**, fails BrowserScan `notPrivate` check (-10 points, flagged as incognito)
  - `--fingerprint-storage-quota=5000`: **Fails FingerprintJS**, passes BrowserScan `notPrivate` check
  - **With Widevine sideloaded:** Can pass both by raising quota (Widevine presence signals real Chrome to FingerprintJS)
- **Cleanup:** Calling `.close()` closes the context and browser. The profile data remains on disk for the next run.

### Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `CLOAKBROWSER_WIDEVINE_CDM` | — | Path to custom `WidevineCdm` directory (overrides auto-detection next to binary). |
| `CLOAKBROWSER_WIDEVINE` | `1` | Set to `0` to disable automatic Widevine hint-file seeding. |

### Source

`cloakbrowser/browser.py:246–371`
```

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

### Basic Persistent Profile Launch and Restore

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-persistent-context.md

Demonstrates launching a persistent context, performing actions, and then restoring the session on a subsequent run by reusing the same profile directory. Cookies and localStorage are automatically restored.

```python
from cloakbrowser import launch_persistent_context

# First run — creates the profile
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://example.com")
page.fill("#email", "user@example.com")
page.fill("#password", "secret")
page.click("button[type=submit]")
ctx.close()

# Second run — cookies and localStorage restored automatically
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://example.com")
# Already logged in — cookies/session state restored
print(await page.text_content(".username"))  # "user@example.com"
ctx.close()
```

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

### Basic Launch

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

Launches a browser instance with a specified proxy and enables GeoIP.

```APIDOC
## launch

### Description
Launches a browser instance with the specified configuration. This function is intended for synchronous contexts.

### Method
launch()

### Parameters
- **proxy** (string | ProxySettings | None) - Optional - The proxy server to use for the browser instance.
- **geoip** (bool) - Optional - If True, enables GeoIP resolution for timezone and locale.
- **headless** (bool) - Optional - If True, the browser runs in headless mode (no UI).

### Example
```python
from cloakbrowser import launch

browser = launch(
    proxy="http://user:pass@residential-proxy:8080",
    geoip=True,
    headless=False,
)
page = browser.new_page()
page.goto("https://ip-detection-test.com")
browser.close()
```

### Notes
- The `.close()` method is patched to automatically stop the underlying Playwright instance. Always call `.close()` to prevent resource leaks.
- Stealth patches are active by default (`stealth_args=True`).
```

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

### Launch pre-configured context (Python)

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

Launches a browser context with pre-defined settings like user agent and viewport. Useful for setting up specific browsing environments.

```python
browser_context = launch_context()
```

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

### Python: Launch with Humanize

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Demonstrates how to launch a browser with the Humanize feature enabled using default settings in Python.

```APIDOC
## Python: Launch with Humanize

```python
from cloakbrowser import launch

# Basic humanization with default preset
browser = launch(humanize=True)
page = browser.new_page()
page.goto("https://example.com")
page.locator("#email").fill("user@example.com")  # Humanized
page.locator("button[type=submit]").click()      # Humanized
browser.close()
```
```

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

### Sideload Widevine CDM for DRM Content

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-persistent-context.md

This snippet demonstrates how to sideload the Widevine CDM (Content Decryption Module) into a persistent context. It involves copying the CDM from a Chrome installation to the profile directory. This setup is necessary for playing DRM-protected content on sites like Netflix.

```python
from cloakbrowser import launch_persistent_context
import os
import shutil

# Copy WidevineCdm from your real Chrome install (one-time setup)
chrome_cdm = "/opt/google/chrome/WidevineCdm"
profile_dir = os.path.expanduser("~/.cloakbrowser/chromium-146.0.7680.177.5")
if os.path.exists(chrome_cdm):
    shutil.copytree(chrome_cdm, f"{profile_dir}/WidevineCdm", dirs_exist_ok=True)

# Now Widevine is seeded on first launch
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://netflix.com")
ctx.close()
```

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

### Launch Browser with Proxy Dictionary Configuration

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

Launches a browser instance using a dictionary for proxy configuration, allowing separate fields for server, bypass, and authentication. This offers more granular control over proxy settings.

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

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

### Install CloakBrowser with Puppeteer

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

Install CloakBrowser and Puppeteer core dependencies.

```bash
npm install cloakbrowser puppeteer-core
```

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

### Launch with Humanization Presets and Custom Config

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

Demonstrates how to launch CloakBrowser with humanization enabled, either using a predefined preset like 'careful' or by providing a custom configuration object to fine-tune specific parameters.

```python
from cloakbrowser import launch, HumanConfig

# Use preset
browser = launch(humanize=True, human_preset="careful")

# Custom config
browser = launch(
    humanize=True,
    human_config={
        "typing_delay": 100,
        "mistype_chance": 0.05,
        "mouse_steps_divisor": 5,  # more steps = smoother curve
    }
)
```

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

### Install CloakBrowser with npm for Puppeteer

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

Install CloakBrowser and Puppeteer core for JavaScript/Node.js projects.

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

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

### Install CloakBrowser with npm for Playwright

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

Install CloakBrowser and Playwright core for JavaScript/Node.js projects.

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

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

### Launch CloakBrowser Context with Options

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

Create a browser context with specified user agent, viewport, locale, and timezone. These are passed as binary flags.

```javascript
const context = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezone: 'America/New_York',
});
```

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

### Install CloakBrowser with NPM

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

Install the CloakBrowser Node.js package using npm. This is the first step to using CloakBrowser in your JavaScript/TypeScript projects.

```bash
npm install cloakbrowser
```

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

### Install GeoIP Extra

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/geoip.md

Install the 'geoip' extra for Python to enable GeoIP support. For JavaScript, GeoIP is automatically available in Node.js.

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

```bash
# GeoIP automatically available in Node.js
npm install cloakbrowser
```

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

### Python: Launch with Anti-bot Site Configuration

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

Launches a browser with specific configurations for bypassing anti-bot measures on protected websites. Includes proxy, GeoIP, non-headless mode, and humanization.

```python
from cloakbrowser import launch

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

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

### Install CloakBrowser for Python

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

Install the CloakBrowser Python package using pip. This is the first step to using CloakBrowser in your Python projects.

```bash
pip install cloakbrowser
```

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

### Launch pre-configured context (JavaScript)

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

Launches a browser context with specific configurations. This allows for setting up custom environments before creating pages.

```typescript
const browserContext = await launchContext();
```

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

### Python: Custom Configuration

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Illustrates how to apply custom configurations for humanization, such as typing delay, mistype chance, and mouse overshoot, in Python.

```APIDOC
## Custom Configuration

```python
from cloakbrowser import launch

browser = launch(
    humanize=True,
    human_config={
        "typing_delay": 100,              # ms per character
        "typing_pause_chance": 0.15,      # 15% chance of pausing
        "typing_pause_range": [500, 1200], # pause duration
        "mistype_chance": 0.05,           # 5% typo rate
        "mouse_steps_divisor": 6,         # smoother curves (more steps)
        "mouse_overshoot_chance": 0.20,   # 20% chance of overshoot
        "idle_between_actions": True,     # idle micro-movements
        "idle_between_duration": [0.5, 1.0],
    }
)
```
```

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

### Install Xvfb for Virtual Display

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

Install Xvfb, a virtual framebuffer, on Debian/Ubuntu systems. This is a prerequisite for running a headed browser on a virtual display.

```bash
sudo apt install xvfb
```

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

### Install Widevine CDM

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

Copies the Widevine CDM directory from a Chrome installation to the CloakBrowser directory. This enables Widevine support for DRM-protected content on Linux.

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

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

### Launch Context with Custom Settings

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

Creates a browser context with specified user agent, viewport, locale, and timezone in a single call. This is a convenience function for setting up a context quickly.

```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: Launch with Custom Humanize Configuration

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Launches a browser with humanized interactions using a custom configuration object. Allows fine-tuning of typing delays, mouse movements, and idle behavior.

```python
from cloakbrowser import launch

browser = launch(
    humanize=True,
    human_config={
        "typing_delay": 100,              # ms per character
        "typing_pause_chance": 0.15,      # 15% chance of pausing
        "typing_pause_range": [500, 1200], # pause duration
        "mistype_chance": 0.05,           # 5% typo rate
        "mouse_steps_divisor": 6,         # smoother curves (more steps)
        "mouse_overshoot_chance": 0.20,   # 20% chance of overshoot
        "idle_between_actions": True,     # idle micro-movements
        "idle_between_duration": [0.5, 1.0],
    }
)
```

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

### Python: Launch with Humanize Presets

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Launches a browser with humanized interactions using predefined presets like 'default' or 'careful'. 'Careful' provides slower, more deliberate interactions.

```python
from cloakbrowser import launch

# Default preset — normal human speed
browser = launch(humanize=True, human_preset="default")

# Careful preset — slower, more deliberate
browser = launch(humanize=True, human_preset="careful")
```

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

### Launch Browser with Proxy and GeoIP

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

Launches a browser instance with a specified HTTP proxy and enables GeoIP resolution. The browser is set to be non-headless for visual inspection. Remember to close the browser instance to prevent resource leaks.

```python
from cloakbrowser import launch

browser = launch(
    proxy="http://user:pass@residential-proxy:8080",
    geoip=True,
    headless=False,
)
page = browser.new_page()
page.goto("https://ip-detection-test.com")
browser.close()
```

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

### launchContext

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/javascript-launch.md

Launches a browser and a pre-configured context in a single call. This function is convenient for setting up a new browser session with specific options.

```APIDOC
## launchContext

Convenience function that launches a browser and pre-configured context in one call.

### Signature

```typescript
async function launchContext(
  options?: LaunchContextOptions
): Promise<BrowserContext>
```

### Type Definitions

```typescript
interface LaunchContextOptions extends LaunchOptions {
  userAgent?: string;
  viewport?: {width: number; height: number} | null;
  colorScheme?: 'light' | 'dark' | 'no-preference';
  contextOptions?: Partial<BrowserContextOptions>;
}
```

### Parameters

All parameters from `LaunchOptions`, plus:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| options.userAgent | string | No | — | Custom User-Agent string. |
| options.viewport | object \| null | No | {width: 1920, height: 947} | Viewport size. Pass `null` to disable emulation. |
| options.colorScheme | 'light' \| 'dark' \| 'no-preference' | No | — | Color scheme preference. |
| options.contextOptions | BrowserContextOptions | No | — | Extra Playwright context options (e.g., `storageState`, `permissions`). |

### Return Value

**Type:** `Promise<BrowserContext>`

A pre-configured ephemeral (incognito) context. Calling `.close()` on the context also closes the browser.

### Example

```typescript
import { launchContext } from 'cloakbrowser';

const context = await launchContext({
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  viewport: {width: 1920, height: 1080},
  locale: 'de-DE',
  timezone: 'Europe/Berlin',
});
const page = await context.newPage();
await page.goto('https://example.com');
await context.close(); // also closes browser
```

#### Restore and save session state

```typescript
import { launchContext } from 'cloakbrowser';

// Load saved session
const context = await launchContext({
  contextOptions: { storageState: 'state.json' },
});
const page = await context.newPage();
await page.goto('https://protected-site.com');

// Save state for next run
await context.storageState({ path: 'state.json' });
await context.close();
```

### Notes

- **Default viewport:** If not specified, uses `{width: 1920, height: 947}`.
- **Incognito by default:** Does not persist state across sessions. Use `launchPersistentContext()` to persist.
- **Context closing:** Calling `context.close()` automatically closes the browser.
```

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

### Get CDP WebSocket Endpoint

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

Fetch the Chrome DevTools Protocol version information to get the WebSocket debugger URL. This can be used to connect directly.

```bash
curl http://localhost:9222/json/version | jq -r .webSocketDebuggerUrl
# ws://localhost:9222/devtools/browser/<browser-id>
```

```bash
curl 'http://localhost:9222/json/version?fingerprint=11111' | jq -r .webSocketDebuggerUrl
# ws://localhost:9222/fingerprint/11111/devtools/browser/<browser-id>
```

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

### Install Noto Color Emoji and other fonts on Debian/Ubuntu

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

Install essential fonts for Linux environments to pass anti-bot checks that rely on canvas rendering, especially for emoji.

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

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

### Python: Presets

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Shows how to use predefined humanization presets ('default', 'careful') when launching the browser in Python.

```APIDOC
## Presets

```python
from cloakbrowser import launch

# Default preset — normal human speed
browser = launch(humanize=True, human_preset="default")

# Careful preset — slower, more deliberate
browser = launch(humanize=True, human_preset="careful")
```

The "careful" preset applies:
- Slower typing (100ms/char vs 70ms)
- More frequent and longer pauses while typing
- More mouse wobble and overshoot
- Longer scroll pauses
- Optional idle micro-movements between actions
```

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

### Start Virtual Display and Set DISPLAY

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

Start the Xvfb virtual display server and set the DISPLAY environment variable. This allows applications to render on the virtual display.

```bash
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
```

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

### Launch pre-configured context asynchronously (Python)

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

Launches a browser context asynchronously with pre-defined settings. Ideal for async applications requiring specific browser configurations.

```python
browser_context = launch_context_async()
```

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

### Set custom binary path

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

Specify a custom download URL or use a local binary if the default download fails or times out.

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

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

### Install GeoLite2 Database Manually

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/geoip.md

If the GeoLite2 database fails to download automatically due to network errors or MaxMind API issues, use this command to attempt a manual installation.

```bash
python -m cloakbrowser install
```

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

### Set Permissions and Headers with launch_context()

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-context.md

Launches a stealth browser with specific permissions (e.g., geolocation, notifications) and custom HTTP headers. Also configures geolocation coordinates.

```python
from cloakbrowser import launch_context

context = launch_context(
    permissions=["geolocation", "notifications"],
    extra_http_headers={"Accept-Language": "de-DE"},
    geolocation={"latitude": 52.5, "longitude": 13.4},  # Berlin
)
page = context.new_page()
page.goto("https://location-aware-site.com")
context.close()
```

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

### Install mmdb-lib for Auto Timezone/Locale

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

Install the mmdb-lib package to enable automatic detection of timezone and locale from a proxy's IP geolocation. This is useful for bypassing antibot systems that check for location consistency.

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

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

### Launch Async Browser Instance

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

Launches an asynchronous browser instance using `launch_async`. This is suitable for use within `asyncio` applications. Remember to `await` browser operations and always call `await browser.close()` to clean up resources.

```python
import asyncio
from cloakbrowser import launch_async

async def main():
    browser = await launch_async()
    page = await browser.new_page()
    await page.goto("https://bot.incolumitas.com")
    print(await page.title())
    await browser.close()

asyncio.run(main())
```

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

### Stagehand Integration (TypeScript)

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

Example of integrating CloakBrowser with the Stagehand framework.

```typescript
// js/examples/stagehand.ts
```

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

### Launch Async Context

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

Provides an asynchronous counterpart to `launch_context()`. It allows for creating browser contexts with custom settings within an asyncio event loop.

```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())
```

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

### Agent Browser Integration (Shell)

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

Example of integrating CloakBrowser with the agent-browser tool using shell scripting.

```shell
// examples/integrations/agent_browser.sh
```

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

### BinaryInfo Interface Definition

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

Defines the structure for binary information, including version, platform, installation status, and path.

```typescript
interface BinaryInfo {
  version: string;      // e.g., '146.0.7680.177.5'
  platform: string;     // 'linux-x64', 'darwin-arm64', etc.
  installed: boolean;
  path?: string;        // Absolute path to binary (undefined if not installed)
}
```

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

### Python: Launch with Default Humanization

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Launches a browser with humanized interactions enabled using default settings. Useful for general realistic simulation.

```python
from cloakbrowser import launch

# Basic humanization with default preset
browser = launch(humanize=True)
page = browser.new_page()
page.goto("https://example.com")
page.locator("#email").fill("user@example.com")  # Humanized
page.locator("button[type=submit]").click()      # Humanized
browser.close()
```

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

### Python: Session Persistence with Persistent Context

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

Demonstrates how to launch a persistent browser context to maintain session data like cookies across multiple runs. The first run logs in, and the second run restores the logged-in state.

```python
from cloakbrowser import launch_persistent_context

# First run: login
ctx = launch_persistent_context("./profile", headless=False)
page = ctx.new_page()
page.goto("https://example.com/login")
page.fill("#email", "user@example.com")
page.fill("#password", "secret")
page.click("button[type=submit]")
ctx.close()

# Second run: cookies restored
ctx = launch_persistent_context("./profile")
page = ctx.new_page()
page.goto("https://example.com")
# Already logged in
ctx.close()
```

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

### Reuse Browser Instance for Multiple Pages

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

Launch a browser once and reuse the instance to create multiple pages. This is more efficient than launching a new browser for each page.

```python
browser = launch()
for url in urls:
    page = browser.new_page()
    page.goto(url)
    # Process...
browser.close()
```

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

### Dockerfile for Building CloakBrowser from Pip

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

Builds a Python 3.12 slim image, installs CloakBrowser and its binary, then copies a user script.

```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_context() with Proxy and Human Behavior

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-context.md

Launches a stealth browser using a specified proxy server and enables human-like behavior with a 'careful' preset. GeoIP detection is also enabled.

```python
from cloakbrowser import launch_context

context = launch_context(
    proxy="http://user:pass@residential-proxy:8080",
    geoip=True,
    humanize=True,
    human_preset="careful",
)
page = context.new_page()
page.goto("https://anti-bot-site.com")
context.close()
```

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

### Launch Browser with Human-like Behavior

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

Launches a browser instance with human-like mouse, keyboard, and scroll movements enabled. This can help in evading bot detection.

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

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

### Launch CloakBrowser with GeoIP Timezone/Locale Detection

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

Automatically set timezone and locale based on the proxy IP address. Requires `mmdb-lib` to be installed.

```javascript
const browser = await launch({
  proxy: 'http://proxy:8080',
  geoip: true,
});
```

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

### Run CloakBrowser Lambda Image with Other Surfaces

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

Demonstrates running the built Docker image with different command-line interfaces, showcasing that other invocation surfaces from the canonical CloakHQ image remain functional.

```bash
docker run --rm -it cloakbrowser-lambda:arm64 python
```

```bash
docker run --rm cloakbrowser-lambda:arm64 python examples/basic.py
```

```bash
docker run --rm -p 9222:9222 cloakbrowser-lambda:arm64 cloakserve --port=9222
```

```bash
docker run --rm cloakbrowser-lambda:arm64 cloaktest
```

```bash
docker run --rm -it cloakbrowser-lambda:arm64 node
```

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

### Basic launch_context() Usage

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/launch-context.md

Launches a stealth browser with a custom user agent and viewport. Remember to close the context to also close the browser.

```python
from cloakbrowser import launch_context

context = launch_context(
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    viewport={"width": 1920, "height": 1080},
)
page = context.new_page()
page.goto("https://example.com")
context.close()  # also closes browser
```

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

### Python: get_default_stealth_args

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/utilities.md

Get the default stealth fingerprint arguments used by the `launch()` function. These arguments are applied automatically unless `stealth_args=False` is specified.

```APIDOC
## Python: get_default_stealth_args

### Description
Get the default stealth fingerprint arguments used by `launch()`.

### Signature
```python
def get_default_stealth_args() -> list[str]
```

### Returns
List of Chromium CLI arguments, e.g.:
```python
[
  '--no-sandbox',
  '--fingerprint=42069',           # random seed
  '--fingerprint-platform=windows' # (on Linux; macos on macOS)
]
```

### Example
```python
from cloakbrowser import get_default_stealth_args

args = get_default_stealth_args()
print("Default stealth args:", args)
```

### Note
These are applied automatically by `launch()` unless `stealth_args=False`.
```

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

### JavaScript: Launch with Humanize

Source: https://github.com/cloakhq/cloakbrowser/blob/main/_autodocs/api-reference/humanize.md

Shows how to launch a browser with the Humanize feature enabled using default settings in JavaScript.

```APIDOC
## Launch with humanize

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

const browser = await launch({
  humanize: true,
  humanPreset: 'default',
});
const page = await browser.newPage();
await page.goto('https://example.com');
await page.locator('#email').fill('user@example.com'); // humanized
await page.locator('button[type=submit]').click();     // humanized
await browser.close();
```
```

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

### Downgrade CloakBrowser to a previous version

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

Install a specific wrapper version to downgrade both the wrapper and the binary it downloads. This is useful if a new update broke functionality.

```bash
pip install cloakbrowser==0.3.21              # Python
```

```bash
npm install cloakbrowser@0.3.21               # JavaScript
```

```bash
docker pull cloakhq/cloakbrowser:0.3.21       # Docker
```

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

### Launch Browser with HTTP Proxy

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

Launches a browser instance configured to use an HTTP proxy. Requires proxy server details including optional authentication.

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

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

### Run CloakBrowser Test with Docker

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

Execute a test directly using Docker without local installation. This command runs a test instance of CloakBrowser.

```bash
docker run --rm cloakhq/cloakbrowser cloaktest
```

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

### Build Custom CloakBrowser Docker Image from Source

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

Builds a Docker image tagged 'cloakbrowser' from the local Dockerfile.

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

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

### CloakBrowser CLI Commands

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

Manage the CloakBrowser binary using command-line interface commands. These include installation, checking status, updating, and clearing the cache.

```bash
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
```

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

### Launch ephemeral browser (JavaScript)

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

Launches a basic ephemeral browser instance in JavaScript. This is the standard way to start a new, clean browsing session.

```typescript
const browser = await launch();
```

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

### Human-like Behavior

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

Launches a browser with human-like interaction patterns enabled.

```APIDOC
## launch (with humanize)

### Description
Launches a browser instance with human-like behavior enabled, making interactions more natural and less detectable as automated.

### Method
launch()

### Parameters
- **humanize** (bool) - Optional - If True, enables human-like interaction patterns.
- **human_preset** (HumanPreset) - Optional - A predefined set of humanization settings (e.g., "careful").
- **human_config** (HumanConfigOverrides | None) - Optional - A dictionary to override or customize humanization settings like typing delay and mistype chance.

### Example
```python
from cloakbrowser import launch

browser = launch(
    humanize=True,
    human_preset="careful",  # slower, more deliberate
)
page = browser.new_page()
page.goto("https://example.com")
# All interactions (click, type, scroll) are now humanized
page.locator("#email").fill("user@example.com")
page.locator("button[type=submit]").click()
browser.close()
```

### Custom Humanize Config Example
```python
from cloakbrowser import launch

browser = launch(
    humanize=True,
    human_config={
        "typing_delay": 100,  # slower typing (ms per char)
        "mistype_chance": 0.05,  # 5% typo rate
        "idle_between_actions": True,
        "idle_between_duration": [0.3, 0.8],
    }
)
```
```