# How to Integrate CloakBrowser with a Browser-Use AI Agent Framework: Complete Implementation Guide

> Integrate CloakBrowser with AI agents by launching its patched Chromium with a remote debugging port. Learn how to pass the CDP endpoint URL to the BrowserSession constructor for seamless integration.

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

---

**You can integrate CloakBrowser with the browser-use AI agent framework by launching CloakBrowser's patched Chromium binary with a remote debugging port and passing the resulting CDP endpoint URL to browser-use's `BrowserSession` constructor.**

CloakBrowser is an open-source Python library that provides stealth browser automation by wrapping a patched Chromium binary with Playwright. When combined with the browser-use framework—an AI agent library that controls browsers via the Chrome DevTools Protocol (CDP)—you can create sophisticated, undetectable web automation agents that leverage large language models while maintaining browser fingerprint privacy.

## Understanding the Integration Architecture

The integration works because CloakBrowser exposes a standard Chrome DevTools Protocol (CDP) endpoint that browser-use expects. This creates a clean separation between the stealth browser layer and the AI agent logic.

### How CloakBrowser Exposes CDP Endpoints

In [`cloakbrowser/browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/browser.py), the `launch_async` function (lines 49-66) starts the patched Chromium binary with custom stealth arguments and returns a Playwright `Browser` object. When you pass `--remote-debugging-port=<port>` in the args list, Playwright automatically opens a CDP server on that port. The library makes this accessible via `browser.cdp_endpoint`, which returns a URL like `http://127.0.0.1:9242` that external tools can connect to.

### How Browser-Use Consumes CDP

The browser-use framework (`pip install browser-use`) provides a `BrowserSession` class that accepts a `cdp_url` parameter. This session object handles the CDP communication, while the `Agent` class orchestrates the LLM interaction. By wiring CloakBrowser's CDP output to browser-use's session input, you create a complete AI-driven automation stack.

## Step-by-Step Implementation Guide

### Launch CloakBrowser with Remote Debugging

First, ensure the patched binary is available. The `ensure_binary()` function in [`cloakbrowser/download.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/download.py) handles automatic downloads. Then launch with debugging enabled:

```python
from cloakbrowser import launch_async

cb_browser = await launch_async(
    headless=True,
    args=[
        "--remote-debugging-port=9242",
        "--remote-debugging-address=127.0.0.1",
    ],
)

```

The `build_args()` function in [`browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/browser.py) merges your custom args with default stealth arguments from [`cloakbrowser/config.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/config.py), ensuring fingerprint protection is active before the CDP server starts.

### Connect Browser-Use Session

Once CloakBrowser is running, extract the CDP URL and initialize the browser-use session:

```python
from browser_use import BrowserSession

session = BrowserSession(cdp_url="http://127.0.0.1:9242")

```

No additional proxy or driver configuration is required because CloakBrowser already manages the underlying Chromium process and its debugging interface.

### Instantiate the AI Agent

Create an `Agent` with your preferred LLM and the browser session:

```python
from browser_use import Agent, ChatOpenAI

agent = Agent(
    task="Go to https://www.google.com and search for 'browser automation'",
    llm=ChatOpenAI(model="gpt-4o-mini"),
    browser_session=session,
)

```

The agent drives the page through the CDP connection while CloakBrowser maintains stealth fingerprinting for timezone, locale, WebRTC IP, and other detectable properties.

## Complete Code Examples

### Basic Integration Example

This complete example from [`examples/integrations/browser_use_example.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/examples/integrations/browser_use_example.py) demonstrates the minimal viable integration:

```python
import asyncio
from browser_use import Agent, BrowserSession, ChatOpenAI
from cloakbrowser import launch_async

async def main():
    # Launch Cloak Browser with default stealth settings.

    cb_browser = await launch_async(
        headless=True,
        args=[
            "--remote-debugging-port=9242",
            "--remote-debugging-address=127.0.0.1",
        ],
    )

    # Connect browser‑use to the CDP server started by Cloak Browser.

    session = BrowserSession(cdp_url="http://127.0.0.1:9242")

    # Create an AI agent that will control the browser.

    agent = Agent(
        task="Go to https://www.google.com and search for 'browser automation'",
        llm=ChatOpenAI(model="gpt-4o-mini"),
        browser_session=session,
    )

    # Run the task and print the result.

    result = await agent.run()
    print(result)

    # Clean up.

    await cb_browser.close()

if __name__ == "__main__":
    asyncio.run(main())

```

### Persistent Profile Session

For maintaining cookies and local storage across agent sessions, use `launch_persistent_context_async`:

```python
from cloakbrowser import launch_persistent_context_async
from browser_use import Agent, BrowserSession, ChatOpenAI

async def main():
    ctx = await launch_persistent_context_async(
        "./my-profile",
        headless=False,
        args=["--remote-debugging-port=9243"],
    )
    # The context also opens a CDP server on the chosen port.

    session = BrowserSession(cdp_url="http://127.0.0.1:9243")
    agent = Agent(
        task="Log in to https://example.com with existing credentials",
        llm=ChatOpenAI(model="gpt-4o-mini"),
        browser_session=session,
    )
    print(await agent.run())
    await ctx.close()

```

### Human-Like Interaction Mode

Enable human-like mouse movements and keyboard input by activating the humanization layer in `cloakbrowser/human/`:

```python
cb_browser = await launch_async(
    headless=False,
    humanize=True,               # Activates human patching

    human_preset="careful",      # Conservative movement patterns

    args=["--remote-debugging-port=9250"],
)

```

The `humanize` flag triggers `patch_browser_async` (implemented around line 140 in [`browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/browser.py)) which injects Playwright scripts mimicking real user behavior patterns.

## Technical Deep Dive: Key Source Files

### Core Launch Functions in browser.py

The [`cloakbrowser/browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/browser.py) file contains the essential `launch_async`, `launch`, and `launch_context` functions that manage the Chromium lifecycle. This file also handles cleanup through `_close_with_cleanup`, ensuring that closing the CloakBrowser instance also terminates the underlying Playwright process to prevent orphan processes.

### Binary Management in download.py

[`cloakbrowser/download.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/download.py) implements `ensure_binary()`, which automatically downloads and caches the patched Chromium binary required for stealth operation. This is called automatically by the launch functions, so the integration requires no manual binary management.

### Stealth Configuration in config.py

Default stealth arguments—including viewport settings, permission policies, and anti-detection flags—are defined in [`cloakbrowser/config.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/config.py) via `get_default_stealth_args()`. These are merged with user-provided arguments in `build_args()` before the browser starts, ensuring the CDP server inherits all fingerprint protection settings.

## Summary

- **CloakBrowser exposes a CDP endpoint** through `--remote-debugging-port` arguments processed by `launch_async` in [`cloakbrowser/browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/browser.py)
- **Browser-use connects via `BrowserSession`** using the CDP URL provided by the CloakBrowser instance
- **No additional drivers** are required because CloakBrowser manages the patched Chromium binary and proxy handling internally
- **Persistent contexts** are available through `launch_persistent_context_async` for maintaining state across AI agent sessions
- **Human-like behavior** can be enabled via the `humanize` parameter, which triggers `patch_browser_async` for realistic interaction patterns

## Frequently Asked Questions

### What is the browser-use framework?

Browser-use is a Python framework that enables AI agents to control web browsers through the Chrome DevTools Protocol (CDP). It provides an `Agent` class that accepts task descriptions and LLM clients (such as OpenAI's ChatGPT), executing web automation through browser sessions while allowing the AI to make decisions based on page content.

### Why use CloakBrowser instead of standard Playwright?

CloakBrowser wraps a patched Chromium binary with additional stealth fingerprinting protections not present in standard Playwright installations. According to the CloakHQ/CloakBrowser source code, it handles timezone spoofing, locale settings, WebRTC IP masking, and automated binary management through `ensure_binary()` in [`download.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/download.py), making it ideal for automation that requires anti-detection capabilities.

### How does the CDP connection work between the two libraries?

When CloakBrowser launches Chromium with `--remote-debugging-port`, Playwright starts a CDP server on that port. CloakBrowser's `browser.cdp_endpoint` property exposes this URL (e.g., `http://127.0.0.1:9242`). Browser-use's `BrowserSession` class accepts this URL via the `cdp_url` parameter and communicates directly with the browser through standard CDP commands, allowing the AI agent to control the stealth browser without modification to either library.

### Can I use persistent browser profiles with this integration?

Yes. Instead of `launch_async`, use `launch_persistent_context_async` from [`cloakbrowser/browser.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/browser.py), passing a profile directory path. This maintains cookies, local storage, and authentication state between agent runs. The context object exposes the same CDP endpoint, so you connect to browser-use exactly as you would with a standard browser instance.