How to Use Browser-Use: The Beginner's Guide (First Install, First Agent, the Task-Design Lesson, and the Stop-Policy Rule)

CodexFuse Team · 2026-11-01T14:25:37.766Z · 16 min read

Learn how to use Browser-Use: install the open-source Python agent framework, run your first AI browser agent, design tasks it can finish, and pick the right LLM.

How to Use Browser-Use: The Beginner's Guide (First Install, First Agent, the Task-Design Lesson, and the Stop-Policy Rule)

Learning how to use browser-use is the moment your automation stops being a script and becomes a junior colleague: instead of telling the browser exactly which element to click, you describe the goal in plain language and an AI agent figures out the clicks itself. Browser-Use is a free, open-source Python library that puts a large language model in a control loop over a real Chromium browser — the agent looks at the page, decides on an action, executes it, then looks again and repeats until the task is done. As of November 2026 it sits at version 0.13.14, holds an MIT license, and has passed 119,000 GitHub stars, which makes it the most-used open-source framework for AI browser automation. This browser-use tutorial runs the complete beginner arc: install, your first agent, the task-design lesson that separates working agents from looping ones, the LLM cost ladder, custom tools, structured output, the stop-policy rule, headless evidence collection, and the honest moment where the hosted cloud becomes worth paying for.

This guide starts with the command line, not a cloud dashboard: you install the library locally, run an agent on your own machine, and only graduate to Browser Use Cloud once you know what each run costs. If the Python environment setup feels new, read the Docker beginner guide first — the container lane is where many teams run these agents later. The agent frameworks itch is related too: read the CrewAI beginner guide for the orchestration sibling — CrewAI coordinates teams of agents, while browser-use gives one agent a browser.

How do you use browser-use?

You use browser-use by installing the Python package, giving an Agent a natural-language task plus a language model, and letting the observe-decide-act loop drive a real browser until it produces a result. The whole beginner path is seven steps:

1. Install Python 3.11 or newer (3.12 recommended) and a package tool such as uv.
2. Install the library with uv pip install browser-use and the browser with uvx browser-use install.
3. Put your model API key in a .env file — or plan to use Ollama locally with no key at all.
4. Write a five-line agent script: Agent(task=..., llm=...), then await agent.run().
5. Start with a public, read-only task so a wandering agent cannot break anything.
6. Design every task with one finish line, a permitted domain, an exact output format, and a stop rule.
7. Run headless, save the run history, and only move heavy or scheduled work to Browser Use Cloud.

What is browser-use, exactly?

Browser-use is an LLM agent loop over a real Chromium browser, say it once: the model reads the page (DOM-first, not screenshots), chooses one of the agent's actions, executes it, observes the new page state, and repeats until it declares the task done. You never write selectors, waits, or navigation logic — you write a sentence, and the model turns that sentence into dozens of small browser operations. That is the entire mental model, and every design decision below follows from it.

The line that matters most is the one between browser-use and deterministic automation. Playwright is the engine browser-use itself runs on — but with Playwright you write the exact sequence: go here, click this, type that. With browser-use you describe the destination and the model finds the route, which means it keeps working when the page changes its layout. The cost of that adaptability is that every step is a model call, so a simple scrape can cost a few cents in tokens instead of nothing. The one-line version of the browser-use vs Playwright question: Playwright scripts what you specify; browser-use explores what you describe.

If you already own a stable Playwright suite, browser-use is not a replacement for it — it is the tool you reach for when the page refuses to stay still. And a browser-use tutorial that shows one framework should say the middle lane exists: Stagehand's act/observe/extract pattern is the compromise position, but it is its own page, not this one.

What do you need before installing browser-use?

You need Python 3.11 or newer, a terminal you are comfortable with, and one API key from a model provider — or nothing at all if you go the Ollama route. The current docs recommend Python 3.12 managed through uv, the fast Python package tool, and the examples in this guide follow that path. The browser-use agent is a Python library first: there is no signup, no dashboard, and no account to create before your first local run.

Get your key from your chosen provider (OpenAI, Anthropic, or Google) and keep it in a .env file the agent loads at startup — never in the task text itself. If you prefer Browser Use's own managed model, you create a BROWSER_USE_API_KEY at cloud.browser-use.com instead; eligible new signups get a one-time $1 cloud credit. The GitHub repo is the home of every example in this guide — the GitHub beginner guide covers cloning and navigating it if you are new there.

How do you install browser-use?

You install browser-use with two commands: one installs the browser-use Python package, the other installs the Chromium browser it drives.

pip install uv
uv venv --python 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install browser-use
uvx browser-use install     # installs the Chromium browser dependency

Say the two-package lesson once: the pip package gives you the agent framework, and uvx browser-use install gives it a Chromium to drive. Older guides tell you to run playwright install chromium, but that command is gone from the current docs — the project's own installer is the supported path now. The quickstart variant uv add browser-use plus uv run agent.py does the same thing inside an uv init --python 3.12 project, which is the shape the current README uses.

How do you run your first browser-use agent?

Your first agent is five lines: create a model, create an Agent with a task, and run it. Save this as agent.py:

import asyncio
from browser_use import Agent, ChatBrowserUse
from dotenv import load_dotenv

load_dotenv()

async def main():
    llm = ChatBrowserUse()
    agent = Agent(
        task="Find the number 1 post on Show HN",
        llm=llm,
    )
    history = await agent.run()
    print(history.final_result())

if __name__ == "__main__":
    asyncio.run(main())

Run it with uv run agent.py and watch the terminal narrate the loop: navigate, extract, click, read, done. Say the read-only-first lesson once: your very first task must be public and read-only — counting stars on a repo, reading a headline, extracting a price list — so that a wandering agent can only waste tokens, never delete data. The run returns an AgentHistoryList, and history.final_result() prints the last extracted result; everything else (visited URLs, screenshots, errors) is sitting in that same object, which the evidence section below unpacks.

What makes a task the agent can actually finish?

A finishable task is a bounded one: one goal, one permitted domain, an exact output format, and an explicit list of things the agent must not do. Vague tasks fail — "research laptops" loops forever — while bounded ones succeed: "On example-shop.com, list the five cheapest wireless keyboards under $50, and return name, price, and URL for each; do not add anything to a cart." Say the task-design lesson once: every task you ever write gets one finish line, a permitted domain, exact output fields, and a no-go list.

The field's best articulation of this comes from AnyGen's browser-use showcase, and it is worth stealing verbatim as your mental checklist: a Goal that defines what "done" means, a Scope that names the source or domain, Fields that make the output testable, a Stop rule such as "if the price is not visible, return not found" so the agent never invents data, and an Action boundary that forbids signing in, submitting, or purchasing. A successful browser interaction is not automatically a correct answer — validate the result against the page itself, every time. That validation habit is what separates a demo from a pipeline.

Which LLM should you give your agent?

You pick from three rungs: Browser Use's own managed model for accuracy-per-dollar, your own provider key for control, or a local Ollama model for zero cost. ChatBrowserUse() with no arguments currently selects BU2 (bu-2-0), the company's model optimized for browser automation, priced at $0.60 per million input tokens, $0.06 cached input, and $3.50 output as of October 2026, and it requires BROWSER_USE_API_KEY. It also accepts provider-prefixed models through the same gateway, like ChatBrowserUse(model='anthropic/claude-sonnet-4-6').

The browser-use Ollama path deserves a line because it is the only one with no API key and no bill: install Ollama, run ollama serve, pull llama3.1:8b (about 4.9 GB), and import it top-level — from browser_use import Agent, ChatOllama — then hand it to the agent like any other model. Every import in the current library is top-level, so if a tutorial shows deep imports like browser_use.agent.service or browser_use.llm.ollama.chat, that tutorial is outdated; the signatures move fast, so verify against the README at write time. Smaller local models are weaker agents than the hosted ones — expect more wandering — but for learning the loop they are free.

How do you teach the agent a custom action?

You give the agent custom tools with the Tools registry and the @tools.action decorator — there is no Controller class anymore. Each action is an async Python function whose description tells the model when to call it, and whose return value is an ActionResult:

from browser_use import Tools, Agent, ActionResult

tools = Tools()

@tools.action(description='Ask a human for help with a question')
async def ask_human(question: str) -> ActionResult:
    answer = input(f'{question} > ')
    return ActionResult(extracted_content=f'The human responded with: {answer}')

agent = Agent(task='...', llm=llm, tools=tools)

The ask_human pattern is worth copying first because it is also your safety valve: whenever the agent is unsure, it calls your tool instead of guessing. Two rules from the docs: description is required because the LLM reads it to decide when to act, and special injectable parameters match by name — use browser_session: BrowserSession, not browser: Browser. You can also restrict where a tool may fire with allowed_domains=['*.example.com'], and you can import whole tool collections from a local MCP server. If writing the whole script by hand feels like a lot, the Browser Use Studio generates the agent.py for you from templates — this guide teaches you to write it yourself; the studio is the generator lane for when you already know what you want.

How do you get structured data out of the agent?

You ask for it declaratively: pass a Pydantic model as output_model_schema to Agent(...), and read the parsed result back from history.structured_output. Instead of hoping the final text happens to be parseable, the agent is instructed to fill your schema — fields, types, and all. The repo's examples/features/custom_output.py is the canonical working example.

The run history object is also your debugging console: history.final_result() for the last extracted content, history.urls() for everywhere it went, history.screenshots() or screenshot_paths() for the visual trail, history.errors() for what went wrong, and history.is_successful() for the agent's own assessment. Read the last one carefully: is_done() only means the agent stopped, not that it succeeded, and is_successful() is the agent grading its own homework. For anything that matters, verify the outcome against the page independently.

What is the stop-policy rule?

The stop-policy rule is simple: the agent stops and asks a human whenever it meets a password, a one-time code, a CAPTCHA, a payment screen, a legal acceptance, an unusual permission, or any action that would send, publish, delete, or transfer something. Never hand an agent credentials or payment steps in a tutorial — say it once. Prefer a safe stop over an unauthorized completion, and never let the agent invent data to fill a gap: "not found" is a correct answer, a hallucinated price is a lie.

Three habits make the rule practical. First, give the agent a dedicated test account with least-privilege roles for its first ten to twenty runs, and keep credentials in the environment, never in the task text. Second, split research from execution: finding the flights is one run, booking them is a second run only after a human picks and authorizes. Third, remember the AnyGen line: browser-use is not a permission bypass — do not use it to evade site rules or solve access controls without authorization. CAPTCHA-solving on your own site with permission is automation; doing it on someone else's is not your call to make.

How do you run headless and keep the evidence?

Headless is the default, and you show the window with Browser(headless=False) while you are learning. Watching the agent work is genuinely useful: you see the moment it misreads a button, which is the moment your task design needs fixing. A sensible window size is window_size={'width': 1280, 'height': 720}, set on the Browser you hand to the agent.

Every run is evidence if you keep it: the screenshots and URL list are the audit trail that lets you prove what the agent actually did, which matters the first time someone asks "did it really click buy?" Long runs can even be saved and replayed without new model calls via agent.save_history('invoice_run.json') and load_and_rerun with variables — with sensitive_data enabled, secrets are stored as placeholders rather than typed values. Say the evidence lesson once: a headless agent that leaves no trail is a black box, and black boxes do not belong in production workflows.

When should you move to Browser Use Cloud?

You graduate to the cloud when local runs become the bottleneck: many parallel sessions, scheduled jobs, or machines without a display. The migration is deliberately tiny — Browser(use_cloud=True) with BROWSER_USE_API_KEY and the same code runs on a hosted stealth browser. Say the graduation line once: the browser-use cloud lane exists for scale, not for learning; your first fifty runs should be local.

The official pricing, verified on browser-use.com in November 2026, is pay-as-you-go with no subscription: cloud browsers cost $0.02 per browser-hour plus $5 per GB of residential proxy traffic, hosted web agents add model tokens plus a 20% service fee, credits never expire, the minimum top-up is $5, and new signups get $1 free once. There is also a fully hosted path via the browser-use-sdk (client.runs.create("...")), where the agent itself runs on their infrastructure. One recent addition worth knowing: since mid-2026, every Browser Use Cloud session ships with its own AgentMail inbox automatically, so agents can sign up for services and pull verification codes with no human in the loop — which is also why the stop-policy rule matters more, not less.

What are the 7 mistakes every browser-use beginner makes?

Sources

• GitHub repo README — github.com/browser-use/browser-use — quickstart code, top-level imports, Browser(use_cloud=True), Tools() custom actions, ChatBrowserUse recommendation, 119,738 stars, MIT license
• PyPI package metadata — pypi.org/pypi/browser-use/json — latest version 0.13.14, requires Python >= 3.11
• Human Quickstart (docs) — docs.browser-use.com/open-source/quickstart.md — uv venv --python 3.12, uv pip install browser-use, uvx browser-use install, .env key setup
• Supported Models (docs) — docs.browser-use.com/open-source/supported-models — ChatBrowserUse BU2 token pricing ($0.60/$0.06/$3.50 per 1M), provider list, Ollama setup
• Ollama example — github.com/browser-use/browser-use/blob/main/examples/models/ollama.py — ChatOllama(model='llama3.1:8b'), Agent(...).run_sync()
• Add Tools (docs) — docs.browser-use.com/open-source/customize/tools/add.md — Tools() + @tools.action, allowed_domains, browser_session: BrowserSession injection
• Output Format (docs) — docs.browser-use.com/open-source/customize/agent/output-format.md — output_model_schema, history.structured_output, AgentHistoryList helpers
• Browser basics (docs) — docs.browser-use.com/open-source/customize/browser/basics.md — Browser(headless=False), window size
• Cloud Agent quickstart (docs) — docs.browser-use.com/cloud/agent/quickstart.md — browser-use-sdk V4 usage, $1 credit note
• Official pricing — browser-use.com/pricing — $0.02/browser-hour, $5/GB proxy, credits never expire, $5 minimum top-up, $1 free once
• AnyGen showcase — anygen.io/showcase/browser-use/index.html — five-part task structure, stop policy, research-vs-execution separation
• Scrapeless integration docs — docs.scrapeless.com/en/integrations/browser-use — install + remote-browser agent example
• AgentMail blog — agentmail.to/blog/how-browser-use-gives-every-browser-agent-its-own-inbox — every Browser Use Cloud session ships with its own inbox (~June 2026)

Frequently Asked Questions

Is browser-use free?

The library is free and MIT-licensed — install it, run agents on your own machine with Ollama, and pay nothing. Costs only appear when you rent intelligence or infrastructure: ChatBrowserUse tokens at $0.60 per million input and $3.50 per million output tokens, your own provider's API bills, or Browser Use Cloud browsers at $0.02 per hour. New signups get a one-time $1 cloud credit, and cloud credits never expire.

Can I use browser-use without any API key?

Yes, with Ollama. Install Ollama, run ollama serve, pull a model like llama3.1:8b, and pass ChatOllama(model='llama3.1:8b') to your agent — everything runs on your hardware with no key and no bill. Expect weaker agents than the hosted models and give tasks extra structure; for learning the observe-decide-act loop it is the perfect starting rung.

How is browser-use different from Playwright?

Playwright is deterministic: you write the exact clicks and it repeats them. Browser-use is adaptive: you describe the goal and the language model figures out the clicks, so it keeps working when a site redesigns its layout. It runs on a real Chromium browser under the hood — Playwright is the engine — but the tradeoff is that every step is a model call costing tokens instead of being free.

Can browser-use handle logins, CAPTCHAs, and checkouts?

Technically it can often get past them, but the stop-policy rule says it should not do so alone: stop and ask a human at any password, one-time code, CAPTCHA, payment screen, or publish action. Use dedicated test accounts, keep credentials out of task text, and split research runs from execution runs so nothing irreversible happens without explicit approval.

Does browser-use work with my model or provider?

Almost certainly. The library ships top-level wrappers for OpenAI, Anthropic, and Google, plus DeepSeek, Groq, Mistral, Cerebras, Qwen, Fireworks, OpenRouter, LiteLLM, AWS Bedrock, OCI, any OpenAI-compatible endpoint, local Ollama models, and Browser Use's own gateway through ChatBrowserUse with provider-prefixed model names. If your provider speaks the OpenAI API shape, point ChatOpenAI at its base_url and go.