Local Installation Guide

Relevant source files

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

• README.md
• requirements.txt
• webui.py
• docker-compose.yml
• supervisord.conf
• src/utils/default_config_settings.py

Introduction

The Local Installation Guide provides comprehensive instructions for setting up the web-ui project, a Gradio-based interface for AI browser agents built on the browser-use foundation. This system allows users to interact with various Large Language Models (LLMs) to automate web-based tasks through a user-friendly interface.

The project supports two primary installation methods: a direct local Python installation and a containerized Docker deployment. The scope of this guide covers environment preparation, dependency management, configuration of environment variables, and the initialization of the web interface.

Sources: README.md:1-25, webui.py:461-470

Installation Methods

Option 1: Native Local Installation

This method involves setting up a Python environment directly on the host machine. It is recommended for developers who wish to modify the source code or run the application with minimal overhead.

1. Clone the Repository: Retrieve the source code from the GitHub repository.

   git clone https://github.com/browser-use/web-ui.git
   cd web-ui
   

2. Environment Setup: The project recommends using uv for virtual environment management, specifically targeting Python 3.11 or higher.

   uv venv --python 3.11
   # Activate based on OS (e.g., source .venv/bin/activate for macOS/Linux)
   

3. Dependency Installation: Install the required Python packages and the Playwright browser engine.

   uv pip install -r requirements.txt
   playwright install
   

Sources: README.md:33-70, requirements.txt:1-5

Option 2: Docker Installation

The Docker installation encapsulates the entire environment, including Xvfb (virtual framebuffer) and VNC servers, ensuring consistent behavior across different platforms (AMD64 and ARM64).

1. Configuration: Copy the .env.example to .env and provide the necessary API keys.
2. Deployment: Use Docker Compose to build and start the services.

   docker compose up --build
   

   To maintain browser state between tasks, set CHROME_PERSISTENT_SESSION=true.

Sources: README.md:83-118, docker-compose.yml:1-15

System Architecture and Initialization

The application relies on a multi-process structure when running in a containerized environment, managed by supervisord. This ensures that the display server, VNC server, and the WebUI start in the correct sequence.

Process Flow Diagram

The following diagram illustrates the startup sequence and dependencies of the system components:

The system initializes the virtual display (Xvfb) before starting the VNC servers. The webui.py application finally launches, binding to the specified IP and port.

Sources: supervisord.conf:1-100, webui.py:821-835

Configuration and Environment

Configuration is handled through a combination of environment variables in a .env file and a default configuration dictionary within the application code.

Key Configuration Variables

Variable	Description	Default/Example
OPENAI_API_KEY	API key for OpenAI models	(Required for OpenAI)
CHROME_PATH	Path to the Chrome executable	/usr/bin/google-chrome
CHROME_PERSISTENT_SESSION	Whether to keep the browser open	false
RESOLUTION	Virtual display resolution	1920x1080x24
VNC_PASSWORD	Password for remote VNC access	vncpassword

Sources: docker-compose.yml:21-41, src/utils/default_config_settings.py:10-35

Application Parameters

The webui.py script accepts several command-line arguments to customize the local execution environment:

• --ip: The IP address to bind the WebUI (default: 127.0.0.1).
• --port: The port to listen on (default: 7788).
• --theme: UI theme selection (e.g., Ocean, Citrus, Monochrome).
• --dark-mode: Boolean flag to enable dark mode.

Sources: webui.py:822-827, README.md:135-151

Execution Logic

The entry point of the application is the main() function in webui.py, which initializes the configuration and launches the Gradio interface.

# webui.py:821-835
def main():
    parser = argparse.ArgumentParser(description="Gradio UI for Browser Agent")
    parser.add_argument("--ip", type=str, default="127.0.0.1", help="IP address to bind to")
    parser.add_argument("--port", type=int, default=7788, help="Port to listen on")
    parser.add_argument("--theme", type=str, default="Ocean", choices=theme_map.keys(), help="Theme to use for the UI")
    args = parser.parse_args()

    config_dict = default_config()
    demo = create_ui(config_dict, theme_name=args.theme)
    demo.launch(server_name=args.ip, server_port=args.port)

The default_config() function provides a baseline state for the agent, including max_steps, use_vision, and headless settings.

Sources: webui.py:821-835, src/utils/default_config_settings.py:10-35

Summary

The local installation of the WebUI project is designed to be flexible, supporting both native Python environments and Docker-based deployments. By configuring the appropriate environment variables and installing the necessary dependencies (Playwright and requirements), developers can quickly deploy an AI-driven browser automation tool with integrated VNC support for real-time interaction monitoring.