browser

harness install browser

The browser package gives the agent a background browser: an isolated headless Google Chrome in which it searches the web, opens pages and reads them, without your screen, mouse, keyboard or Chrome profile.

Install

harness install browser

The app installs it the first time a conversation needs it. It installs Playwright into the worker's environment but does not download a browser: Google Chrome must be installed on this computer. It runs on Windows, macOS and Linux.

To record tiled browser windows (below), install ffmpeg as well.

Use

Every new conversation asks where it works: choose Background browser (beside the model in the app, in the opening choice of the terminal chat, --workspace browser on the command line). To stop the question, set session.environment to browser or last under /settings.

Then type the task, for example: "Find the opening hours of the city library and the nearest bus stop."

The agent searches, opens URLs and reads the visible page text. The model reads the page text and links with read_page() and its controls with elements(), and sees the page when a program looks (look()). Activity → Background browser in the app previews the page without changing its viewport. Each new conversation starts with fresh cookies; follow-up messages in the same conversation keep its page. Use Stop and Continue to pause and resume; there is no foreground window to take over (Interrupt and take over).

A program the agent writes looks like this:

search_web("city library opening hours")
page = read_page()
print(page["title"], page["url"])
print(page["text"][:2000])
for link in page["links"][:10]:
    print(link["text"], link["url"])
navigate("https://example.org/library/hours")
page = read_page(offset=0, limit=12000)
if page["next_offset"]:
    more = read_page(offset=page["next_offset"])

Several at once

Background browsers run side by side. Each conversation works in a workspace of its own: a worker with its own context (cookies, storage and pages kept apart) in a headless Chrome the background browsers share. Settings → Computer sets how many conversations work at once and how many headless Chromes they share. Beyond that number, a new conversation ends the one that has waited longest for you, or waits until one ends; Restart stops the workspaces no conversation uses.

For a suite, an experiment with bench = "browser" runs its seeds in N such workspaces at once with --workspaces N:

harness run my-browser-tasks.toml --workspaces 4

Tiled windows and screen recording

To watch or record the background browsers, set computer.browser_windows to tiled and choose the screen region with computer.browser_area. Turn on computer.record_screen to record each conversation's tiled screen as screen.mkv beside its trace. Each frame records its wall-clock time. Use harness replay to turn the conversation and recording into a video. Replay a run

On Linux, browser_display opens the tiled windows on another X display, such as a virtual screen, instead of this computer's own.

What it provides

• Bench browser: an isolated headless Chrome for web search and browsing, one task, free, whose instruction is yours. It uses the computer embodiment.
• Skill browser:
  • search_web(query) searches the web in the background page; read_page() then reads the results.
  • navigate(url) opens an http(s) URL (one input step).
  • elements(role=None, text=None, limit=200) and act(id, action, value) use the desktop skill's interface on live controls in the current document. Each id belongs to that page and document.
  • read_page(offset=0, limit=12000) returns a dictionary with text, links, url, title, offset, total_chars and next_offset; continue at next_offset on a long page.
• Workspace kind browser: one of the environments a conversation chooses, in every frontend; another conversation can also take it with use_environment("browser", why).

Settings

Set in the app under Settings → Computer or in the terminal chat under /settings.

Key	Default
mode	browser	browser starts new conversations in a background browser
workspaces	4	conversations of any kind that work at once
chromes	1	headless Chromes the background browsers share; more use more memory, and a Chrome that crashes takes only its own conversations with it
browser_locale	system	the language the browser asks websites for: a tag such as en-US, or system
browser_windows	off	off (headless) or tiled (one window per conversation or agent, tiled on one screen)
browser_area	0,0,1920,1080	tiled: x,y,width,height of the part of the screen they are tiled in
browser_display	empty	tiled: the X display the windows open on; empty is this computer's own screen
record_screen	off	on with tiled windows: record the screen for each conversation, for harness replay (needs ffmpeg)
max_side	1920	screenshots are scaled to at most this many pixels on the long side; the viewport is at most 1440 pixels wide
step_limit	300	browser input steps a conversation may take

Limits and known issues

• Element actions cover the top document and open shadow roots. The managed input path refuses opaque targets, including frames it cannot inspect.
• It browses and searches only: no native apps, no downloads, and no login handoff. When a site needs a login or blocks automated browsers, the agent reports it. To work in local apps, choose This desktop or Apps in the background (the computer package).
• It never uses desktop capture, global input, the system clipboard or your Chrome profile, so you can keep using the computer.
• Page content is treated as untrusted material, not as instructions.
• Every screenshot goes to the model provider with the request.

0.5.2

• Package removal retains shared immutable cache files for other projects and independently configured data directories, and updates choose compatible versions while keeping your declared ranges. Explicit updates refresh published versions, including in a running app. A project install paused for trust refuses changed declarations instead of overwriting them. Preparing path, Git or URL sources and waiting for trust leave other package commands available. If another package change is already publishing files or records, a new request stops promptly and asks you to retry after it finishes. Broken environment caches rebuild on first use; installation errors show their cause and retry only transient network failures, and the terminal uses its declared dependency pins. Browser depends on computer 0.8, and current browser, computer and external-agents packages require Harness 0.82 or newer. The core refuses older computer packages with an upgrade command instead of running an incompatible managed-workspace protocol. Project updates change the lock without turning indirect dependencies into declarations; outside a project, --update --project refuses to touch user packages. Installing from a project's declarations preserves its source references and ranges, including legacy local-path records. Named dependency updates respect retained parent packages' constraints; jointly updated or replaced parents use their new dependencies. Local sources stay local and resolve relative to the project root; older URL records remain usable. Manifest installs retain compatible registry locks. Dependency changes, including local replacements, respect retained parents and recorded ranges; incompatible existing records are refused before writes. The old computer/browser pair has one joint-upgrade command, and obsolete project lock conflicts explain explicit removal. Cache reuse checks source identity and compatibility, including identical-version switches from development copies or another registry. Cleanup refuses the working directory, its ancestors, the home directory and filesystem roots. Registry mirrors are recognized by identical archive checksums; implicit lock restore refuses different or missing content until you explicitly update or select a source. Source selection updates project declarations and dependencies together. Automatic installation respects development/disabled choices and pinned ranges; updates preserve enabled state and select versions compatible with the current platform. Capability recovery refreshes an already installed provider and restores missing selected cache files without dropping owner settings. Recovery commands retain saved ranges; unnamed development dependencies and unavailable project locks refuse before writes, and missing-cache lock restoration checks its archive checksum. Automatic recovery validates existing registry content in every scope, while explicit updates keep their selection authority. Dependency recovery names compatible joint commands, registry read failures preserve their real cause, and ready installed capabilities remain available before installation-policy gates without repeated change notifications. Recovery commands stay limited to the related installed packages, including with obsolete lock entries or a stray lock. First-use installation of a new provider applies the same protection to already selected shared dependencies.

0.5.1

• Depend on computer 0.7: with the range left at 0.5 the package could not be installed beside the current computer package.

0.5.0

• The page is no longer sent with every turn: read_page() and elements() give it as text, and look() shows it when a program needs the picture. The background browser can be taken into another conversation with use_environment("browser", why). Requires Harness 0.80.0.

0.4.3

• Use core shared agent prompts with Harness 0.75.0. Browser provisioning and controls remain in their existing packages.

0.4.2

• For the harness 0.65: the pack's last section lists the installed skills ({ installed = true }).

0.4.1

• An agent's pointer shows from its first page on: until it clicks, it rests near the page's top left (REST), its name readable, not at 0,0.

0.4.0

• For the harness 0.63: Its dependencies' new versions.

0.3.4

• For the harness 0.62.2: The browser shield's rejection is the core's reject.

0.3.3

• The prompt's input steps and way of working come from the computer package's prompts/desktop (steps.md, programs.md); core.md keeps the page, reading it, its keys and its own calls.
• Depends on computer 0.4.3, which has these sections.

0.3.2

• A browser window shown draws its agent's pointer with its name in its colour (the pointer method): it glides to each click, scroll and drag, stays out of the page's events, text and accessibility, and comes back on every page. The state says how windows show (layout).
• Needs computer 0.4.2.

0.3.1

• For the harness 0.62: declares its practice sandbox: none yet.

0.3.0

• For the harness 0.59: it depends on computer 0.3 (workers start as python -m harness.core.worker).

0.2.0

• For the harness 0.58: Imports what moved out of harness.sdk from the packages that hold it now.

0.1.0

• First release as a package of its own (moved out of the harness core).