web-ui/README.md

<img src="./assets/web-ui.png" alt="Browser Use Web UI" width="full"/>

<br/>

[![GitHub stars](https://img.shields.io/github/stars/browser-use/web-ui?style=social)](https://github.com/browser-use/web-ui/stargazers)
[![Discord](https://img.shields.io/discord/1303749220842340412?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://link.browser-use.com/discord)
[![Documentation](https://img.shields.io/badge/Documentation-📕-blue)](https://docs.browser-use.com)
[![WarmShao](https://img.shields.io/twitter/follow/warmshao?style=social)](https://x.com/warmshao)

This project builds upon the foundation of the [browser-use](https://github.com/browser-use/browser-use), which is designed to make websites accessible for AI agents.

We would like to officially thank [WarmShao](https://github.com/warmshao) for his contribution to this project.

**WebUI:** is built on Gradio and supports a most of `browser-use` functionalities. This UI is designed to be user-friendly and enables easy interaction with the browser agent.

**Expanded LLM Support:** We've integrated support for various Large Language Models (LLMs), including: Gemini, OpenAI, Azure OpenAI, Anthropic, DeepSeek, Ollama etc. And we plan to add support for even more models in the future.

**Custom Browser Support:** You can use your own browser with our tool, eliminating the need to re-login to sites or deal with other authentication challenges. This feature also supports high-definition screen recording.

**Persistent Browser Sessions:** You can choose to keep the browser window open between AI tasks, allowing you to see the complete history and state of AI interactions.

<video src="https://github.com/user-attachments/assets/56bc7080-f2e3-4367-af22-6bf2245ff6cb" controls="controls">Your browser does not support playing this video!</video>

## Installation Options

### Option 1: Docker Installation (Recommended)

1. **Prerequisites:**
   - Docker and Docker Compose installed on your system
   - Git to clone the repository

2. **Setup:**
   ```bash
   # Clone the repository
   git clone <repository-url>
   cd browser-use-webui

   # Copy and configure environment variables
   cp .env.example .env
   # Edit .env with your preferred text editor and add your API keys
   ```

3. **Run with Docker:**
   ```bash
   # Build and start the container with default settings (browser closes after AI tasks)
   docker compose up --build

   # Or run with persistent browser (browser stays open between AI tasks)
   CHROME_PERSISTENT_SESSION=true docker compose up --build
   ```

4. **Access the Application:**
   - WebUI: `http://localhost:7788`
   - VNC Viewer (to see browser interactions): `http://localhost:6080/vnc.html`
   
   Default VNC password is "vncpassword". You can change it by setting the `VNC_PASSWORD` environment variable in your `.env` file.

### Option 2: Local Installation

Read the [quickstart guide](https://docs.browser-use.com/quickstart#prepare-the-environment) or follow the steps below to get started.

> Python 3.11 or higher is required.

First, we recommend using [uv](https://docs.astral.sh/uv/) to setup the Python environment.

```bash
uv venv --python 3.11
```

and activate it with:

```bash
source .venv/bin/activate
```

Install the dependencies:

```bash
uv pip install -r requirements.txt
```

Then install playwright:

```bash
playwright install
```

## Usage

### Docker Setup
1. **Environment Variables:**
   - All configuration is done through the `.env` file
   - Available environment variables:
     ```
     # LLM API Keys
     OPENAI_API_KEY=your_key_here
     ANTHROPIC_API_KEY=your_key_here
     GOOGLE_API_KEY=your_key_here

     # Browser Settings
     CHROME_PERSISTENT_SESSION=true   # Set to true to keep browser open between AI tasks
     RESOLUTION=1920x1080x24         # Custom resolution format: WIDTHxHEIGHTxDEPTH
     RESOLUTION_WIDTH=1920           # Custom width in pixels
     RESOLUTION_HEIGHT=1080          # Custom height in pixels

     # VNC Settings
     VNC_PASSWORD=your_vnc_password  # Optional, defaults to "vncpassword"
     ```

2. **Browser Persistence Modes:**
   - **Default Mode (CHROME_PERSISTENT_SESSION=false):**
     - Browser opens and closes with each AI task
     - Clean state for each interaction
     - Lower resource usage

   - **Persistent Mode (CHROME_PERSISTENT_SESSION=true):**
     - Browser stays open between AI tasks
     - Maintains history and state
     - Allows viewing previous AI interactions
     - Set in `.env` file or via environment variable when starting container

3. **Viewing Browser Interactions:**
   - Access the noVNC viewer at `http://localhost:6080/vnc.html`
   - Enter the VNC password (default: "vncpassword" or what you set in VNC_PASSWORD)
   - You can now see all browser interactions in real-time

4. **Container Management:**
   ```bash
   # Start with persistent browser
   CHROME_PERSISTENT_SESSION=true docker compose up -d

   # Start with default mode (browser closes after tasks)
   docker compose up -d

   # View logs
   docker compose logs -f

   # Stop the container
   docker compose down
   ```

### Local Setup
1.  **Run the WebUI:**
    ```bash
    python webui.py --ip 127.0.0.1 --port 7788
    ```
2.  **Access the WebUI:** Open your web browser and navigate to `http://127.0.0.1:7788`.
3.  **Using Your Own Browser:**
    - Close all chrome windows
    - Open the WebUI in a non-Chrome browser, such as Firefox or Edge. This is important because the persistent browser context will use the Chrome data when running the agent.
    - Check the "Use Own Browser" option within the Browser Settings.

### Options:

### `--theme`

- **Type**: `str`
- **Default**: `Ocean`
- **Description**: Specifies the theme for the user interface.
- **Options**:
  The available themes are defined in the `theme_map` dictionary. Below are the options you can choose from:
  - **Default**: The standard theme with a balanced design.
  - **Soft**: A gentle, muted color scheme for a relaxed viewing experience.
  - **Monochrome**: A grayscale theme with minimal color for simplicity and focus.
  - **Glass**: A sleek, semi-transparent design for a modern appearance.
  - **Origin**: A classic, retro-inspired theme for a nostalgic feel.
  - **Citrus**: A vibrant, citrus-inspired palette with bright and fresh colors.
  - **Ocean** (default): A blue, ocean-inspired theme providing a calming effect.

**Example**:

```bash
python webui.py --ip 127.0.0.1 --port 7788 --theme Glass
```

### `--dark-mode`

- **Type**: `boolean`
- **Default**: Disabled
- **Description**: Enables dark mode for the user interface. This is a simple toggle; including the flag activates dark mode, while omitting it keeps the interface in light mode.
- **Options**:
  - **Enabled (`--dark-mode`)**: Activates dark mode, switching the interface to a dark color scheme for better visibility in low-light environments.
  - **Disabled (default)**: Keeps the interface in the default light mode.

**Example**:

```bash
python webui.py --ip 127.0.0.1 --port 7788 --dark-mode
```

## (Optional) Configure Environment Variables

Copy `.env.example` to `.env` and set your environment variables, including API keys for the LLM. With

```bash
cp .env.example .env
```

**If using your own browser:** - Set `CHROME_PATH` to the executable path of your browser and `CHROME_USER_DATA` to the user data directory of your browser.

You can just copy examples down below to your `.env` file.

### Windows

```env
CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
CHROME_USER_DATA="C:\Users\YourUsername\AppData\Local\Google\Chrome\User Data"
```

> Note: Replace `YourUsername` with your actual Windows username for Windows systems.

### Mac

```env
CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
CHROME_USER_DATA="~/Library/Application Support/Google/Chrome/Profile 1"
```

## Changelog

- [x] **2025/01/06:** Thanks to @richard-devbot, a New and Well-Designed WebUI is released. [Video tutorial demo](https://github.com/warmshao/browser-use-webui/issues/1#issuecomment-2573393113).