How are browser sessions, profiles, auth and anti-bot handled?

BrowserSession model. BrowserSession (browser_use/browser/session.py:134) is the central session manager, owning CDP WebSocket connections, target/session maps, and an event bus coordinating 12+ watchdogs. Configuration is stored in a BrowserProfile (browser_use/browser/profile.py) which controls browser launch args, proxy, extensions, display config, domain filtering, etc. The session supports both Pydantic model construction and direct parameter overloading from a comprehensible API surface.

Local vs Cloud browsers. Two modes: local launches a Chrome/Chromium process via CDP, providing temporary or persistent profiles, and cloud creates remote browser instances through cloud.browser-use.com API (browser_use/browser/cloud/cloud.py). Cloud mode authenticates via BROWSER_USE_API_KEY env var or auth config file, calls the cloud API's /v{2,3,4}/browsers endpoint to get a CDP URL, then connects normally. Proxy country codes are configurable for geo-targeting. The agent auto-detects which mode via BrowserProfile.use_cloud or explicit cloud_browser_params.

Persistent profiles and cookies. BrowserProfile supports user_data_dir for persistent profiles, and storage_state for saved cookies/session data from Playwright's storage format. The StorageStateWatchdog saves/restores cookies and local storage on browser connect/disconnect. Cookies are loaded from a file specified in BrowserProfile.storage_state or from a user-data-dir profile. The DownloadStorageStateEvent is dispatched when saving state.

Stealth and anti-detection. Chrome is launched with automation-control flags disabled ('--disable-blink-features=AutomationControlled', browser_use/browser/profile.py:201). Multiple fingerprint-reducing Chrome components are disabled (CHROME_DISABLED_COMPONENTS list, browser_use/browser/profile.py:45-93), including AutomationControlled, HeavyAdPrivacyMitigations, CalculateNativeWinOcclusion, OverscrollHistoryNavigation. Cloud browsers add proxy rotation and stealth fingerprinting on the server side.

Proxies. ProxySettings (in BrowserProfile) supports HTTP/SOCKS5 proxies with authentication. Cloud browsers offer country-code proxy selection (ProxyCountryCode). The SecurityWatchdog enforces allowed_domains/prohibited_domains lists, intercepting navigation attempts to blocked domains at the CDP level.

Watchdog architecture. BrowserSession uses an event-bus pattern with specialized watchdogs (browser_use/browser/watchdogs/): LocalBrowserWatchdog (Chrome process launch), DownloadsWatchdog (PDF auto-download with filename sanitization), PopupsWatchdog (JS alerts/dialogs), SecurityWatchdog (domain filtering, IP blocking, sensitive data), DOMWatchdog (DOM snapshot + element highlighting), ScreenshotWatchdog (screenshot capture + optional resize), CaptchaWatchdog (proxy CAPTCHA solver events), AboutBlankWatchdog (empty page redirects), CrashWatchdog (browser crash detection), StorageStateWatchdog (cookie/profile persistence), PermissionsWatchdog (browser permission management), RecordingWatchdog/HARRecordingWatchdog. Each watchdog attaches handlers to the session's event bus and is started/stopped with the browser lifecycle.

CDP connection management. BrowserSession.connect() establishes a WebSocket to the CDP URL, initializes a CDPClient, creates a SessionManager for target/session tracking, enables page monitoring (lifecycle events, accessibility), and dispatches BrowserConnectedEvent. WebSocket reconnection handles transient disconnects with exponential backoff (3 attempts, 1/2/4s delays, 54s total timeout). Connections carry an intentional-stopped flag so cleanup handlers don't cascade.

CAPTCHA. The CaptchaWatchdog listens for CDP BrowserUse.captchaSolverStarted/Finished events from the browser proxy (e.g., the cloud browser's integrated solver or a third-party solving service). It exposes wait_if_captcha_solving() which the agent loop calls. Cloud browsers' proxy-based CAPTCHA solver is claimed to reduce CAPTCHA encounters via stealth fingerprinting and IP rotation.

Local browser (localBrowser.ts): The SDK launches a Chrome/Chromium process with CDP remote debugging enabled (--remote-debugging-port). It auto-detects Chrome on the system (macOS: canonical paths; Windows: Program Files; Linux: PATH). Configurable via LocalBrowserLaunchOptions: headless, viewport, proxy, locale, userDataDir (persistent profile), args (extra flags). Default flags disable background networking, component updates, sync, hang monitor, and prompt-on-repost. A data directory is created per-session (temp dir) and cleaned up on close unless preserveUserDataDir: true. The sandbox is disabled on Linux root or CI.

Browserbase cloud (browserbaseSession.ts): Sessions are created via @browserbasehq/sdk with extensive configuration:

• Stealth/fingerprint: advancedStealth, fingerprint (browser/device/OS/locale/screen simulation)
• Proxies: Browserbase managed proxies (BrowserbaseProxyConfigSchema with geolocation) or external proxies (ExternalProxyConfigSchema with server/credentials)
• Regions: us-west-2, us-east-1, eu-central-1, ap-southeast-1
• CAPTCHA handling: solveCaptchas, captchaInputSelector, captchaImageSelector
• Persistence: context.id + context.persist for persistent browser contexts across sessions
• Recording: recordSession, logSession
• Verification: verified sessions for high-trust sites
• BlockAds, os, viewport

Extension provisioning (browserbaseExtension.ts): The Stagehand extension (packed as a .zip archive) is uploaded to Browserbase and attached to the session. Uploads retry up to 4 times with backoff.

Cookies and headers: BrowserContext in the understudy (context.ts) supports addCookies, clearCookies, setExtraHTTPHeaders, and setDomainPolicy (for domain-specific fetch interception). Cookies are manipulated via the CDP Web.ARC or native cookie stores.

Connection modes: The client can either create a new session (with an optionally provisioned extension) or reconnect to an existing session by session ID (connectSession). The CDP URL (webSocketDebuggerUrl) is used to establish the WebSocket transport.

Lifecycle: The Stagehand.create() to stagehand.close() lifecycle ensures browser claims are released and sessions are invalidated on ambiguous init failures (via claimStagehandBrowser/releaseStagehandBrowser/invalidateStagehandBrowser in factories.ts).