browser-use/web-ui: a Gradio front end that drives a browser agent with your own Chrome profile

What browser-use/web-ui actually adds on top of browser-use

The underlying library, browser-use, is the component that makes websites accessible to an AI agent. This repository does not replace it. It puts a Gradio interface in front of it, so instead of writing a Python script per task you type the task into a form, pick a model, and watch the run. The README states the UI "is built on Gradio and supports most of browser-use functionalities." The audience is therefore people who already want browser automation driven by an LLM but do not want to author orchestration code for every experiment: QA engineers scripting repetitive form flows, analysts pulling the same figures off a portal each morning, or anyone evaluating whether an agent can complete a task before investing in a programmatic integration. The repository is Python, licensed MIT, and its last push was on 2026-05-15, so the codebase is not stale, though nothing in the README describes a release cadence you could plan around.

The mechanism: Gradio form, agent loop, persistent browser context

The data flow is short. webui.py starts a Gradio server. The form collects a task string plus model and browser settings. Those settings reach the agent through environment variables loaded from .env, which is why the config file, not the UI, is where provider credentials live. The agent then drives a Playwright-controlled browser. Two design choices shape how that feels in practice. First, custom browser support: you can point the tool at your own Chrome binary and user data directory, which the README frames as removing the need to re-login to sites or handle authentication challenges. Second, persistent sessions: the .env key KEEP_BROWSER_OPEN, defaulted to true in the example file, keeps the window alive between tasks so state carries over. The Docker path swaps the visible browser for a headless X display plus VNC, which is how the same agent loop becomes observable inside a container. requirements.txt pins browser-use==0.1.48, gradio==5.27.0 and langgraph==0.3.34, so the UI and the agent library move as one unit rather than tracking upstream independently.

Installing browser-use/web-ui and running a first task

The README gives two paths. Local installation uses uv for the Python environment and Playwright for the browsers. Clone the repository and create a Python 3.11 virtual environment first.

git clone https://github.com/browser-use/web-ui.git
cd web-ui
uv venv --python 3.11

Activate it. On macOS or Linux the README gives this line; Windows users get separate Command Prompt and PowerShell variants in the README.

source .venv/bin/activate

Install the pinned Python dependencies and the Playwright browser binaries. The second command is the one people forget, and without it the agent has nothing to drive.

uv pip install -r requirements.txt
playwright install chromium --with-deps

Copy the example environment file and open it in an editor. This is where the LLM keys and the browser settings go.

cp .env.example .env

At minimum the README expects an API key and a default model. The example file ships with DEFAULT_LLM=openai and an empty OPENAI_API_KEY, so a first run needs one of those filled in, or a switch to a local provider such as Ollama at OLLAMA_ENDPOINT=http://localhost:11434.

OPENAI_API_KEY=sk-your-key-here
DEFAULT_LLM=openai

Start the interface and open it in a browser.

python webui.py --ip 127.0.0.1 --port 7788

The README says to navigate to http://127.0.0.1:7788. You should see the Gradio form with fields for the task, the model provider and the browser settings. Type a task, submit it, and the agent begins operating the browser. If you want the agent to use your real Chrome profile, set BROWSER_PATH and BROWSER_USER_DATA, close every Chrome window, and open the WebUI in Firefox or Edge instead, because the persistent context will claim the Chrome data. Then tick "Use Own Browser" in Browser Settings. The Docker route is shorter but adds a VNC viewer: docker compose up --build, then http://localhost:7788 for the UI and http://localhost:6080/vnc.html for watching the browser, with the default VNC password "youvncpassword". On Apple Silicon the README specifies TARGETPLATFORM=linux/arm64 docker compose up --build.

Where the design constrains you: pinned agent, single user, no documented rollback

The tightest constraint is the pin on browser-use==0.1.48. The UI is coupled to one agent version, so fixes and behaviour changes in the agent library do not arrive until this repository bumps the pin, and moving the pin yourself means testing against a UI that was not written for that version. The second is scope: Gradio serves a single interface with no authentication layer described anywhere in the README, and the .env file holds API keys in plaintext. Running this on a shared host or exposing port 7788 beyond localhost is not something the documentation prepares you for. Third, the use-your-own-browser feature asks you to close Chrome entirely and switch to a different browser for the UI, which is a real workflow interruption, not a checkbox. Fourth, the README does not document a rollback path, a migration guide between releases, or what changes between v1.7, v2.0.0 and v3.0.0 beyond release titles. If you need to reproduce a run months later, the pinned requirements help, but the absence of documented upgrade steps means you are reading diffs yourself. Finally, the README describes the LLM provider list as something the project plans to extend, so provider coverage should be checked against the .env.example keys rather than assumed.

browser-use/web-ui against a plain browser-use script or a hosted agent product

The honest alternative is not another UI. It is using browser-use directly in Python, without Gradio in between. The difference is control over the loop: a script lets you branch on the agent's output, retry with a different model, log structured results, and run headless in CI, none of which the Gradio form exposes. What you give up is the interactive inspection the UI provides, particularly the ability to watch the persistent browser and the VNC stream while a task runs. If your goal is a one-off task or a demonstration, the UI saves time. If your goal is a repeatable pipeline, the UI is the wrong layer and the agent library underneath is the thing to integrate. Hosted browser-agent products occupy different ground again: they remove the environment setup and the Chrome profile problem, at the cost of sending your browsing session and credentials to someone else's infrastructure. The README's custom browser section is explicitly about avoiding re-login and authentication friction, which is exactly the property a hosted service cannot offer.

Maintenance, upgrades and what the MIT licence does not settle

The repository is not archived and the last push was on 2026-05-15. Nothing in the README states a support policy, a deprecation window, or a compatibility guarantee across the v1.7, v2.0.0 and v3.0.0 releases. Treat upgrades as manual: read the diff, re-run your tasks, and expect the browser-use pin to be the variable that breaks first. The MIT licence covers the code in this repository, and it is permissive enough for commercial internal use, but it does not cover the LLM providers you connect to, the browser-use library itself, or the sites your agent visits. Those carry their own terms, and an agent operating a logged-in session on a third-party site raises questions the licence text does not answer. The .env.example file also includes an ANONYMIZED_TELEMETRY setting, defaulted to false, which is worth knowing about before you decide what to leave on. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt browser-use/web-ui if you want a local Gradio panel over the browser-use agent and you accept pinning browser-use==0.1.48 yourself. Skip it if you need a stable public API, a multi-user deployment, or a project whose README documents upgrade paths; it does not. Before committing, verify that the DEFAULT_LLM value in .env matches a provider key you actually hold, that port 7788 is free, and that your Chrome profile is closed when USE_OWN_BROWSER is true.

Frequently asked questions

Official sources

1. browser-use/web-ui on GitHub
2. Issues
3. License: MIT
4. README
5. Releases