fastbrowse 0.5.19

Browser automation with results you can verify.

Complete workflows, return cited answers or structured data, and check the result before your application acts on it. Jev chooses actions from the page; code controls credentials, authorization and spending.

Why

fastbrowse indexes the page into candidates and has Jev, a choice model, pick one, so it cannot click something that was never on the page. Every claim in an answer cites a verbatim quote from the page.

13 steps in 20.9s on local Chrome, shown 1.4x faster with pauses cut.

Against Browser Use agents

The Ultrafast comparison covers six navigation tasks against Browser Use Ultrafast (jev-ultrafast). Earlier hosted-agent comparisons and their grading limitations remain in the eval history. Scored-run medians exclude earlier outage attempts. The full audit includes every retry, first-attempt outcomes, unknown charges and the two HN pairs excluded from both arms.

Measured on 2026-09-29 with the build released as 0.5.14: 6 tasks, 120 selected results across all arms, on cloud browsers.

Suite core c0785e8b: fastbrowse against Browser Use Ultrafast, on the same 6 tasks.

Each arm has 60 selected results, excluding earlier retries. Unavailable results: 2 for fastbrowse. Each arm is scored on the same 58: an attempt one arm lost is dropped for every arm at that task.

Controlled mock-site comparison

Release 0.5.9, 2026-09-28. Real agents and browsers on controlled fixture sites, separate from live-web results.

Confirmation gates are scored separately from task completion. Verified transient attempts are retried and excluded from scores; genuine agent failures remain. Full protocol and attempt records are in docs/evals.md.

Compare rows only at matching task versions. See eval results and workflow.

Why fastbrowse, against each kind of agent

• LLM agents that generate actions (the hosted Browser Use agent and similar): Jev picks each action from the controls that are on the page, so there is no invented selector to retry. Every claim in the answer links to the page text it came from.
• Choice-model navigators (Browser Use Ultrafast, the jev-ultrafast package and eval arm): both choose actions with Jev. fastbrowse adds cited answers, schema-validated data, scoped credentials and an authorization gate. Navigation tasks compare the page each run ended on. This navigation result does not establish a winner for every workflow.
• Scripts: there are no selectors to maintain. The same agent handles a date picker, a checkout and a search box it has never seen.

Try it

Needs uv; uv fetches Python itself (3.13 or newer). Runs use a Browser Use Cloud browser (BROWSER_USE_API_KEY) by default: it passes bot checks a fresh local Chrome fails. Local Chrome is fully supported with --local. A browser already running anywhere, from a container to a hosted browser with a CDP endpoint, is driven in place with --cdp-url ws://… or --cdp-port 9222: the run opens one tab and leaves the browser as it was found. To drive a window that is already open, such as an Electron app, see Open windows and Electron apps. A Node program needs neither uv nor Python: see Use it from JavaScript.

export OPENROUTER_API_KEY=...   # for Jev and the LLM that plans and reads
# export AI_GATEWAY_API_KEY=... # optional Jev backup through the Vercel AI Gateway
export BROWSER_USE_API_KEY=...  # the cloud browser; or pass --local to use Chrome
uvx fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/

Jev uses direct TypeSafe when TYPESAFE_API_KEY is supplied; otherwise OpenRouter is primary. Vercel AI Gateway is supported as a backup or an explicit primary. FASTBROWSE_JEV_SOURCE overrides automatic selection; see provider routing. The LLM uses OpenRouter.

uvx runs the published package in an isolated cached environment. uv tool install fastbrowse keeps it on your PATH, and uv add fastbrowse puts it in a project. Service keys can live in a .env file in the working directory; .env.example shows the settings. Values named by --secret must be in the process environment.

To work on fastbrowse itself:

git clone https://github.com/agent-labs-dev/fastbrowse.git && cd fastbrowse
uv sync --all-extras   # the extras carry mcp and browser_use_sdk, which the tests and evals import
cp .env.example .env   # then fill in the keys, BROWSER_USE_API_KEY included, or pass --local
uv run fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/

Steps go to stderr; the status, cost, step count and answer go to stdout. --json prints every step, the quotes behind the answer, and cost by component.

export SAUCE_PASSWORD=secret_sauce
uv run fastbrowse "Log in as standard_user with the saved password and add the backpack to the cart." \
  --start https://www.saucedemo.com/ --secret password=SAUCE_PASSWORD --authorize

Signed-in sites

Sign in once by hand in a profile of its own, then point runs at it:

google-chrome --user-data-dir="$HOME/.fastbrowse/amazon" https://www.amazon.com/   # sign in, then close Chrome
uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --profile ~/.fastbrowse/amazon --headed

On a cloud browser the profile lives on the Browser Use Cloud account rather than on disk, and --cloud-profile ID runs as it. Whoever signed that profile in did so once, in a browser of their own; the run inherits the cookies and no model is shown a credential:

uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --cloud-profile prof_1234

Or from your vault, with the Bitwarden CLI unlocked. The item's saved URIs must match --start; values are then typed only on that origin, and models see only the names username and password, plus one_time_code when the item holds an authenticator key (the current code, computed as it is typed):

export BW_SESSION="$(bw unlock --raw)"
uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --bitwarden Amazon --profile ~/.fastbrowse/amazon --headed

To change a password, supply its replacement as an origin-scoped secret named new_password, alongside the existing password. Refer to new_password in the task and use --authorize to allow submission. Without the replacement secret, the run asks for input; it never generates a password or reuses the old one.

Open windows and Electron apps

An Electron app is Chromium underneath, so a run can drive it once the app exposes a DevTools port. Quit the app, start it again with --remote-debugging-port (an app that is already running ignores the flag), then attach to its window by title or URL. VS Code titles each window after the folder it has open:

open -a "Visual Studio Code" --args --remote-debugging-port=9222 ~/code/my-project   # elsewhere, pass the flag to the binary
uv run fastbrowse "Open the Extensions view and report how many extensions are installed." \
  --cdp-port 9222 --target-match my-project

The same works for a Chrome you started with --remote-debugging-port. With --attach, the run takes over an existing window instead of opening a tab of its own. Without --start it begins on whatever the window shows, and the window stays open when the run ends. --target-match picks the first window whose title or URL contains the text; --attach alone takes the first window, skipping DevTools. Popups the window opens join the run. Windows that nothing opened, as an Electron app's main process opens them, join only with --target-match, because in a browser such a window could equally be a tab you opened yourself.

A DevTools port gives any program on the machine full control of the app, including its signed-in sessions. Close the app, or restart it without the flag, when you are done.

Models

The LLM defaults to google/gemini-3.8-flash at low reasoning effort, with google/gemini-3.5-flash-lite for planning, proposing a direct address and typing field text. Override with FASTBROWSE_LLM_MODEL (every purpose), FASTBROWSE_LLM_MODEL_<PURPOSE> (PLAN, READ, FIELD_TEXT, SHORTCUT, RECOVER, COMPOSE, VERIFY) and FASTBROWSE_LLM_REASONING (low, medium, high).

Results

The exit code identifies the run status. Configuration refusals exit 1; invalid command syntax exits 2. Programs that only check zero versus nonzero continue to work.

A budget_exceeded JSON result includes budget.resource (steps, seconds, dollars, jev_calls or llm_calls) and budget.limit. Other results have budget: null. The embedding and MCP APIs carry the same optional object, so callers can identify the exhausted limit without parsing an error message.

How it works

The LLM plans, reads and writes. Code owns the gates: irreversible actions stop without --authorize, secrets reach models by name only, and supported cookie banners are refused through autoconsent. More in docs/design.md.

How it compares

Browser Use Ultrafast (jev-ultrafast) is Browser Use's navigation agent, separate from its hosted LLM agent; fastbrowse shares its core techniques. Its column describes commit 1231850a, the version pinned by the eval runner.

Embed it

uv add fastbrowse first, then:

import asyncio

from pydantic import BaseModel

from fastbrowse import run_task
from fastbrowse.models import Limits


class Release(BaseModel):
    package: str
    version: str


async def main() -> None:
    result = await run_task(
        "Find the httpx package and report its name and latest released version.",
        start="https://pypi.org/",
        output_schema=Release,
        limits=Limits(max_dollars=0.10),
    )
    print(result.status, result.data, f"${result.cost.known_dollars:.4f}")
    for evidence in result.evidence:
        print(f'  "{evidence.quote}" from {evidence.url}')


asyncio.run(main())

run_task(cdp_url=...) drives a browser that is already running, wherever it is, instead of starting one: the run opens its own tab and closes the tabs it owns. It leaves the browser and pre-existing tabs open; cookies and other changes made by the task can persist. cdp_port= finds the same browser from its DevTools port on 127.0.0.1. attach=True and target_match= drive a window already open and leave it open, as --attach and --target-match do. Pass browser_api_key= to start a cloud browser; with neither argument, it runs local Chrome. Passing both is an error. cloud_extensions=[...] loads up to three of your account's ready Browser Use Cloud extensions, by ID, into that cloud browser; it is an error with local or attached browsers.

connect_cdp() hands a script of your own the attached page, without the agent. Downloads go to downloads=, or to a scratch directory removed on exit:

from fastbrowse import connect_cdp


async def main() -> None:
    async with connect_cdp(9222, target_match="my-project") as page:
        print(await page.observe())

resolve_cdp_port(port) returns the ws:// URL behind a DevTools port, for a caller that passes cdp_url=.

RunResult.citations is a tuple of Citation objects, also importable from fastbrowse. Each has id (the number in the answer), text (the Notes fact), requirement_id (or None), url, quote and deep_link. Each claim in result.answer carries numbered Markdown links to its supporting facts. Counts, totals and superlatives also cite the records they were derived from, including records read on earlier pages. Only verified Notes facts supply citation URLs and quotes; an answer citing an unknown reference fails the claim check, and the run falls back to an answer drafted from verified facts. Facts omitted from the answer have no citation, and citation numbers can have gaps.

Deep links follow the WICG Text Fragments syntax: url#existing-anchor:~:text=start. Text is percent-encoded, including hyphens, ampersands and commas. Whitespace is collapsed for the link; quote keeps the verbatim capture. Quotes over 120 characters with more than ten words use the first and last five words as text=start,end. An existing anchor is preserved; an old text directive is replaced. Pages that change or require a session may no longer show the quote.

To show a run as it happens, pass on_event=: a BrowserEvent arrives first with the live-view URL of a cloud browser, then a StepEvent per step. Config(step_frames=True) adds a PNG of the page each step acted on, for an interface that renders the run; a step whose page is showing a resolved secret sends no frame. StepEvent.step.facts (also StepResult.facts) holds only the facts added by that step: text, requirement id, quote, URL, deep link and reader (jev_choice or llm), with resolved secrets redacted before delivery. StepResult.note carries read outcomes, dispatch details, gate refusals or recovery guidance when available; it can be None for an ordinary successful action.

For continuous live images, pass an async on_frame handler accepting JPEG bytes. Frames follow the active tab and are acknowledged after delivery, with no fixed frame rate. Only the latest pending frame is kept. Handler failures are logged without stopping the run. Live frames and recordings are held back while a resolved secret may show on the page, as PNG step frames are. No handler means no live capture.

Jev uses direct TypeSafe when keyed, otherwise OpenRouter, with Vercel AI Gateway also supported. See Jev routing for key precedence, overrides and failover. Any other source can be passed as run_task(jev=...), implementing async evaluate(state, questions); run_task(llm=...) accepts an implementation of the LLMClient.generate(...) protocol in fastbrowse.llm.

Use it from JavaScript

npm install fastbrowse gives a Node program the same agent, with no Python and no uv on the machine. The package is a TypeScript SDK with no dependencies. With it npm installs one of five packages that hold the agent as a native binary, the one for your platform: @fastbrowse/darwin-arm64, darwin-x64, linux-arm64, linux-x64 or win32-x64. No install script runs and nothing is downloaded on first use, so it installs under pnpm and bun with scripts blocked, and it starts offline. It needs Node.js 20 or newer. The npm packages carry the PyPI package's version and are published by the same tag, starting with the release after 0.5.18.

The binary brings no browser. It finds local Chrome, starts a Browser Use Cloud browser, or drives one already running, as the command line does. It reads the same keys from the environment of your process (OPENROUTER_API_KEY, and BROWSER_USE_API_KEY for a cloud browser); env in Fastbrowse.start adds to them.

npm install fastbrowse zod
export OPENROUTER_API_KEY=...

import { Fastbrowse } from 'fastbrowse';
import { z } from 'zod';

const Release = z.object({ package: z.string(), version: z.string() });

const fb = await Fastbrowse.start({ local: true });
try {
  const result = await fb.run('Find the httpx package and report its name and latest released version.', {
    start: 'https://pypi.org/',
    output: Release,
    limits: { maxDollars: 0.1 },
    onEvent: event => {
      if (event.type === 'step') console.error(event.step.operation, event.step.target);
    },
    signal: AbortSignal.timeout(120_000),
  });
  console.log(result.status, result.answer);
  if (result.status === 'complete') console.log(result.output.package, result.output.version);
  for (const evidence of result.evidence) console.log(`  "${evidence.quote}" from ${evidence.url}`);
} finally {
  await fb.close();
}

Fastbrowse.start starts one fastbrowse process and run sends it a task. The process serves one run at a time: a second run while one is active rejects with the busy error, and a program that wants runs side by side starts more instances. close() shuts the process down and waits for it. The process also exits when yours does, however yours ended.

run resolves with the result whatever status the run ended in, so needs_login or stuck is read from status and is not an exception. It rejects when no run took place or none finished: with RpcError when the server refuses the request before a browser opens (a bad option, a missing key, a busy server), with AbortError when signal stopped the run, and with ProcessExitedError when the process is gone. A run that fails after it has started resolves with status error.

The result is the RunResult the Python library returns, with the same statuses, citations and cost lines. Its fields keep their Python names, such as final_url, since the types are generated from the Python models; the options are camelCase. The structured data is in data, as in Python. The SDK adds output: with a Zod (4.2 or newer) or ArkType schema, or a Valibot schema wrapped by @valibot/to-json-schema, output is data after the schema's own validation and transforms, and has the schema's output type. Data the schema refuses rejects with OutputValidationError, which carries the result. A JSON Schema object is accepted too; output is then data, typed unknown.

What a run can fill today is narrower than what a schema can say. The server accepts nested objects, arrays, enum, const and optional values, and refuses any other keyword by name before a browser opens. A run fills a flat object of required string, number, integer and boolean fields, as the example has. With any other field the run ends unverified with no data.

The callbacks that keep credentials and the last word in your code cross the process boundary:

await fb.run('Log in as standard_user with the saved password and add the backpack to the cart.', {
  start: 'https://www.saucedemo.com/',
  authorization: { irreversibleActions: true },
  secrets: {
    refs: [{ name: 'password', origins: ['https://www.saucedemo.com'] }],
    resolve: name => vault.get(name),
  },
  until: url => url.endsWith('/cart.html'),
});

secrets.resolve is called each time a value is typed and never for an origin its ref does not cover, so the value leaves your vault at that moment and a one-time code is fresh. until gets the address the run ended on, and anything but true keeps the run from complete. onFrame receives JPEG frames of the active tab; without it no frame is sent. A callback that throws ends the run with status error. The other options are the command line's: inputs, attachments as bytes, downloads, record, and the browser choices chrome, cloudProfile, cdpUrl, cdpPort, attach, targetMatch and proxyCountry, which Fastbrowse.start also takes as defaults for every run. A run passes null for one of them to go without that default.

There is no binary for Alpine or another musl system, and none for a platform outside the five. There Fastbrowse.start rejects with an error that names the platform, and a binary of your own is named with binaryPath or FASTBROWSE_BINARY. The macOS binaries carry an ad-hoc signature and are not notarized, which a Mac that allows programs only by the team that signed them refuses. The Windows binary is not signed. Bun and Deno are untested.

Use it from an MCP client

fastbrowse-mcp serves one browse tool over MCP, so Claude Code, Claude Desktop, Cursor or any other MCP client can hand it a task. It returns the answer, typed fields if asked for, the quotes behind them, the status and what to do about it, and reports progress on every step. The answer contains numbered Markdown links. MCP's citations list contains quote and url from the run's evidence; it does not expose the Python Citation ids, requirement ids or deep-link fields.

claude mcp add fastbrowse -e OPENROUTER_API_KEY=... -e BROWSER_USE_API_KEY=... \
  -- uvx --from 'fastbrowse[mcp]' fastbrowse-mcp --max-dollars 0.25

For a client configured by JSON, such as Claude Desktop:

{
  "mcpServers": {
    "fastbrowse": {
      "command": "uvx",
      "args": ["--from", "fastbrowse[mcp]", "fastbrowse-mcp"],
      "env": { "OPENROUTER_API_KEY": "...", "BROWSER_USE_API_KEY": "..." }
    }
  }
}

The server's flags decide what a calling model may do; a call can ask for less, never more.

Over HTTP, set FASTBROWSE_MCP_TOKEN in the environment or .env and every request but /healthz needs Authorization: Bearer <token>. The server refuses to bind anything but loopback without one. A run takes seconds to minutes, so raise the client's tool timeout if it has one (MCP_TOOL_TIMEOUT in Claude Code).

Safety model

• Irreversible actions. Jev judges clicks, including links, Enter presses and acceptance of confirm, prompt or before-unload dialogs. Code-selected pagination is exempt, as are authorized actions with sufficient confidence. A refusal appears as a failed step with a reason: an unauthorized, confident action stops at needs_confirmation; an uncertain action goes to recovery. This is a classifier, not a guarantee: a page can word a harmful control to look harmless.
• Secrets. Models see secret names only. A value is resolved at the moment of typing, only for its declared origin, and redacted from everything the run returns. A password field is typed only from a stored secret, never generated.
• Page content is data. Reader and verifier prompts say so, and completion is judged against quotes and page state rather than the model's say-so.

Evals and development

The eval workflow has the run, publish and regeneration commands. Final page checks require evidence read by the harness, and a pass also requires the task's expected ending. Published rows carry build and task versions; the site feed is generated from them.

See CONTRIBUTING.md for setup and checks, docs/design.md for the browser layer, and docs/jev.md for the Jev assumptions checked against Typesafe's documentation.

Changelog

What changed in each release is in CHANGELOG.md, and every GitHub release publishes that version's entry.

License

MIT, copyright Agent Labs. Adapted third-party code is credited in NOTICE.