Browser Contexts & Sessions

Relevant source files

The following files were used as context for generating this wiki page:

• src/browser/custom_context.py
• src/browser/custom_browser.py
• webui.py
• src/utils/deep_research.py
• README.md
• docker-compose.yml
• supervisord.conf
• tests/test_browser_use.py

Introduction

The Browser Context and Session management system is a core component of the Web-UI project, responsible for orchestrating the lifecycle of browser instances and their associated data environments. It enables the application to support both transient, task-specific browsing and persistent sessions that maintain user state, such as logins and cookies, across multiple AI agent interactions. Sources: README.md:16-30, webui.py:46-55

This system provides a wrapper around Playwright and the browser-use library, introducing custom classes like CustomBrowser and CustomBrowserContext. These extensions allow for fine-grained control over browser configuration, including headless modes, security settings, window dimensions, and the ability to connect to existing local browser profiles. Sources: src/browser/custom_browser.py, webui.py:186-215, src/utils/deep_research.py:41-58

Core Architecture & Components

The architecture relies on a hierarchical structure where a Browser instance manages one or more BrowserContext objects. The Web-UI implements global persistence to allow agents to "re-use" the same browser environment between different tasks.

Class Relationship Diagram

The following diagram illustrates the relationship between the custom browser classes and their configuration entities.

Key Classes & Structures

Component	Description
CustomBrowser	Extends the base browser to handle custom configurations like local Chrome paths and security overrides.
CustomBrowserContext	Manages a specific browsing session, including page lifecycle, recordings, and trace files.
BrowserConfig	Defines high-level settings such as headless mode and chrome_instance_path.
BrowserContextConfig	Defines session-specific settings like trace_path, window_size, and save_recording_path.

Sources: webui.py:20-30, src/utils/deep_research.py:20-35

Persistent Sessions

A significant feature of the Web-UI is the ability to maintain "Persistent Browser Sessions." This is achieved through two primary mechanisms: local environment configuration and Docker-based persistence.

Persistence Logic

In webui.py, global variables _global_browser and _global_browser_context are used to store active instances. If the user selects the "Keep Browser Open" option, these instances are not closed upon task completion, allowing subsequent tasks to inherit the previous state.

Configuration Options

Users can configure persistence via the UI or environment variables:

• CHROME_PERSISTENT_SESSION: Boolean flag in .env or docker-compose.yml to force persistent mode. Sources: README.md:105-110, docker-compose.yml:26
• CHROME_USER_DATA: Path to a local directory used to store browser profile data (cookies, history). Sources: README.md:95-100, webui.py:192-196
• CHROME_PATH: Executable path for a custom browser instance. Sources: src/utils/deep_research.py:45-50, webui.py:189-192

Session Lifecycle in Deep Research

The deep_research.py module demonstrates a specialized session lifecycle for complex, multi-iteration tasks. It supports both standard automated contexts and the use of a "own browser" context.

Deep Research Session Flow

1. Initialization: Creates a CustomBrowser with optional user-data-dir if use_own_browser is enabled.
2. Context Creation: Generates a new context via browser.new_context().
3. Task Execution: Parallel agents share or create contexts based on the research plan.
4. Tab Management: In "own browser" mode, it manually closes tabs after iterations to prevent resource exhaustion while keeping the main session active.
5. Final Cleanup: The finally block ensures browser_context.close() and browser.close() are called to prevent orphan processes.

Sources: src/utils/deep_research.py:38-60, src/utils/deep_research.py:228-245

VNC & Docker Integration

For Docker deployments, the browser session is managed within a virtual framebuffer (Xvfb) and exposed via VNC for real-time monitoring.

Service	Configuration File	Purpose
xvfb	supervisord.conf	Provides a virtual display (DISPLAY=:99) for the browser.
x11vnc	supervisord.conf	Exports the virtual display to the VNC protocol on port 5901.
novnc	supervisord.conf	Provides a web-based interface for VNC on port 6080.
persistent_browser	supervisord.conf	A background process that keeps Chromium running with remote debugging enabled.

Sources: supervisord.conf:9-85, docker-compose.yml:12-16

Summary

The Browser Context and Session system provides a flexible environment for AI agents to interact with the web. By leveraging both global persistent instances for UI-driven tasks and isolated contexts for parallel operations (as seen in Deep Research), the project balances state retention with resource management. Configuration is centralized via BrowserConfig and BrowserContextConfig objects, allowing easy customization of the browsing environment across different deployment platforms. Sources: webui.py:186-215, src/utils/deep_research.py:38-60