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

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, 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 handles automatic downloads. Then launch with debugging enabled:

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 merges your custom args with default stealth arguments from 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:

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:

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 demonstrates the minimal viable integration:

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:

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

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) 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 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 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 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
• 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, 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, 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.

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