Browser-Use + Ollama: Build a Local Web-Browsing Agent (No API Costs)

Short answer: uv pip install browser-use, uvx browser-use install, then ChatOllama(model="qwen3-vl:8b") — that is a web-browsing agent with $0 in API costs. Browser-use is the biggest open-source browser agent there is (107.9K GitHub stars, MIT license, v0.13.7 as of late July 2026) and it supports Ollama first-party. The part most tutorials skip: model size decides everything. An 8B model (~6GB VRAM) completes simple lookups and fails multi-step tasks; the docs themselves warn small models return broken action schemas; things only get dependable around the 30B tier (~20GB). This guide gives you the working setup and an honest map of that line.

Every command, class name, and model size below was verified against the browser-use docs, PyPI, the GitHub repo, and the Ollama model library in August 2026. Where a reliability claim comes from browser-use's own benchmarks or issue tracker rather than our own machines, we say so inline.

---

What Browser-Use Is — and Why Run It Locally

Browser-use is a Python library (MIT, 107.9K stars) that hands a Chromium browser to an LLM: the model reads the page's element tree — plus screenshots if it can see — and emits structured actions like click, type, and scroll until the task is done. You write one sentence ("find the number 1 post on Show HN"); the agent does the clicking.

It is not a research toy. The project self-reports an 89.1% success rate on the WebVoyager benchmark, and its own benchmark of 100 deliberately hard browser tasks is worth internalizing before you form expectations of any model, cloud or local: Claude Fable 5 tops their leaderboard at 80%, and Browser Use Cloud reports 78% — which they describe as "16 points ahead of the best open-source model" (all figures are browser-use's published results, not ours). Even the best cloud stacks miss a fifth of hard web tasks, and open models trail them by double digits. Keep that bar in mind when a 6GB local model stumbles — the ceiling is lower than the demos suggest for everyone.

So why local? Three reasons that hold up:

• Cost. The hosted product charges from $0.36/M input and $1.44/M output tokens plus $0.02/browser-hour (browser-use pricing, August 2026). Browser agents are token furnaces — every step re-sends a chunk of the page. Local tokens are free.
• Privacy. A browser agent sees whatever your browser sees: logged-in sessions, internal dashboards, prices, PII. With Ollama, none of it leaves your machine — same argument that anchors our local AI agents guide.
• No key, no meter, no cutoff. The README's own FAQ lists "run local models with Ollama" as the way to use the library without any provider API key.

The trade you make is reliability, and the rest of this page is about managing that trade honestly.

---

Hardware & Model Requirements

Minimum useful setup: 8GB of VRAM and an 8B model. Comfortable setup: 24GB and a 30B-class model. Browser-use itself is a thin Python layer — your hardware budget is entirely about the model behind it.

Sizes below are official Ollama library download sizes (August 2026). Rule of thumb: VRAM needed = download size + headroom for context, and browser-use needs more context headroom than a chatbot because each step carries the page's element tree.

Two practical notes. First, if you are on 8GB, our 8GB VRAM model picks cover which quants leave room for the context window this workload needs. Second, if you are speccing a machine for agents in general — not just this library — the local agent hardware guide covers the build math, and the 24GB VRAM picks show what that tier unlocks beyond browsing.

CPU-only works in the sense that it runs; a 30-step browser task at CPU token speeds is an afternoon. We don't recommend it beyond a smoke test.

---

Setup: Install to First Run

Four commands install everything; the fifth runs your first agent. Python 3.11+ required (the docs' venv uses 3.12); current release v0.13.7, July 27, 2026 (PyPI).

Quoted from the official quickstart, August 2026:

pip install uv
uv venv --python 3.12
source .venv/bin/activate
uv pip install browser-use
uvx browser-use install   # downloads the Chromium build the agent drives

Then make sure Ollama is serving and pull a model. That side is three steps — install Ollama, ollama serve, pull a model (llama3.1:8b is the usual starting point, a 4.9GB download):

ollama serve          # if it isn't already running
ollama pull llama3.1:8b
ollama pull qwen3-vl:8b   # our suggested step up: adds vision, 6.1GB

And the minimal agent, adapted from the docs' example with the official Ollama import:

from browser_use import Agent, ChatOllama
import asyncio

async def main():
    llm = ChatOllama(model="qwen3-vl:8b")
    agent = Agent(
        task="Go to news.ycombinator.com and return the title of the top post",
        llm=llm,
    )
    await agent.run()

asyncio.run(main())

No .env file, no API key. The quickstart's BROWSER_USE_API_KEY / OPENAI_API_KEY variables belong to the cloud-model path — the Ollama path needs none of them. A Chromium window opens, the model starts reasoning in your terminal, and the meter never runs.

If Ollama lives on another box (a common homelab pattern), ChatOllama takes a host parameter — ChatOllama(model="qwen3-vl:8b", host="http://192.168.1.50:11434") — along with timeout and ollama_options, all confirmed in the class source.

---

Wiring Ollama Properly

Three settings separate a frustrating local agent from a workable one: a big context window, a generous timeout, and vision set to match your model.

1. Raise the context window. Browser-use's per-step messages include the page's element tree, and busy pages produce long prompts. Ollama's default context window is conservative, and a silently truncated prompt is the classic source of malformed actions and loops. Pass it through ollama_options:

llm = ChatOllama(
    model="qwen3-vl:8b",
    ollama_options={"num_ctx": 32768},  # VRAM permitting; try 16384 on 8GB
    timeout=120,
)

More context costs VRAM — this is why the "requirements" table adds headroom beyond the download size.

2. Set the timeout for local speeds. A 30B model on consumer hardware can take a while per step; the default HTTP timeout tuned for cloud APIs will cut it off mid-thought. timeout=120 is a sane floor for the bigger tiers.

3. Match vision to the model. The Agent's use_vision parameter defaults to "auto" (screenshots available, used when asked for); False removes the screenshot tool entirely (docs, August 2026). Run text-only models like llama3.1:8b or qwen2.5 with use_vision=False so the agent never tries to show images to a model that cannot see, and leave "auto" for qwen3-vl. Browser-use's DOM-first design is precisely why text-only local models are viable here at all — vision helps on canvas-heavy and badly-labeled UIs, but the element tree does most of the work.

One more dial worth knowing: max_actions_per_step (default 4) lets the model batch actions like filling several form fields at once. Small local models get less reliable when batching; dropping it to 1-2 trades speed for fewer schema errors.

For the underlying skill this all rests on — models emitting well-formed structured calls — our tool calling guide for Ollama and best agent models roundup are the deeper references.

---

What Local Models Can Actually Do

The honest answer: small local models fail a lot, and the project's own issue tracker says so. Smaller models return malformed action schemas — and in our reading of the tracker that is the defining failure mode of the whole local path, across model families.

Here is the documented evidence, so you can calibrate before burning an evening:

• The 8B tier is an entry point, not an endorsement. It is the size most walkthroughs start with because it fits everywhere, not because it finishes hard tasks.
• The issue tracker, checked August 2026: an open bug (#5017, filed June 2026) reports "Invalid JSON error in browser-use while using ollama vision models" from a user who tried models up to 27B parameters; an open PR (#5023) to strip invalid options and improve JSON error handling for the Ollama provider was still unmerged as we wrote. Translation: even mid-size local models still trip on the action schema, and contributors are actively sanding this path.
• Browser-use's own hard-task benchmark (their numbers): the best score on their 100-task set is 80%, and their cloud product claims to sit 16 points ahead of the best open-source model. If the strongest cloud stacks still miss a fifth of hard tasks and open models trail them by double digits, a 6GB local model failing most hard tasks is not a broken setup — it is the expected result.

What that means task-by-task — a calibration guide, not a benchmark we ran:

Three habits move the needle more than model shopping: write tasks like instructions to a temp on their first day ("go to X, click Y, copy Z" beats "research the best Y"); keep tasks short and chain several small agent runs instead of one epic; and watch the terminal reasoning — when a model starts looping on a selector, no amount of patience fixes it, but a more specific task usually does.

And if what you really want is automation of applications rather than websites, the vision-first approach in our UI-TARS desktop automation guide attacks the same problem from the screenshot side, while the Hermes agent stack is the stronger local pick for tool-calling agents that don't need a browser at all.

---

Honest Limitations

Use browser-use + Ollama for private, low-stakes, well-specified browsing tasks. Do not build anything mission-critical on the local path yet. Where it genuinely creaks:

• Reliability is the product of model size, and local tops out low. The schemas-from-small-models problem is documented in the tracker (issues #5017/#5023), and no prompt engineering fully closes the gap to the tuned cloud models the project's headline numbers come from.
• It is slow. Every step is a full LLM inference over a long prompt. A task a human does in 40 seconds can take a local 30B model several minutes. Fine for unattended jobs; maddening interactively.
• The repo moves fast. v0.13.7 shipped in late July 2026 and imports have changed across versions (ChatOllama now comes straight from browser_use). If a snippet from an older tutorial fails, trust the current docs — including over this page, eventually.
• Token appetite makes context management your job. Long tasks accumulate history; small VRAM budgets force small num_ctx; truncation causes exactly the failures the tracker is full of. This is the hidden coupling most tutorials never mention.
• An agent driving a real browser is a real security surface. It clicks what a model tells it to click, and prompt-injection via page content is an unsolved problem across every browser-agent framework, not just this one. Keep it away from sessions that can spend money or delete things, local model or not.

None of this argues against the setup — it argues for entering with calibrated expectations. A local browser agent that reliably handles the boring 60% of lookups and form-fills, for free, in private, is worth having. Just don't promise it the other 40%.

---

Sources

• Browser-use docs — quickstart install commands and the Agent parameter defaults (use_vision, max_actions_per_step), checked August 2026
• Browser-use GitHub repository — 108K stars, MIT license, the ChatOllama class and its host/timeout/ollama_options parameters, README FAQ on Ollama, and issues #5017 / #5023 (checked August 2026)
• PyPI: browser-use — v0.13.7, tagged July 27, 2026; Python >=3.11 requirement
• Browser-use published benchmarks and pricing — the WebVoyager 89.1% claim, the 100-hard-task leaderboard, and the $0.36/$1.44 per-million and $0.02/browser-hour rates (all self-reported by browser-use, checked August 2026)
• Ollama model library — qwen3-vl, qwen2.5, and llama3.1 tags and download sizes, August 2026

---

FAQ