Overview

The agent gets a real browser through ONE tool: browser(action, ...params) - a single flat schema keyed by action, not two dozen separate tools. It exists on every surface:

Surface	Engine	What it can do
Desktop app	Embedded, tabbed Chromium (visible panel)	Everything: drive, screenshot, audits, throttling, network recording, dev-server runner
TUI + headless	Headless system webview	Drive, snapshot, screenshot, inspect, eval, tabs - no visible panel, no DevTools profiling

The same prompt works on both: snapshot refs, click/type/key (chords included), scroll, resize presets, wait, highlight, clear_storage.

Local-dev only

open/navigate accept localhost and private-network addresses only. Public internet URLs are blocked by default - the browser is for the app you are building, not for web browsing. Opt out per project with terminalBrowserAllowExternal: true (terminal) or the desktop's network-policy setting.

Snapshot first

browser(action:'snapshot') returns every visible interactive element as a short text tree with a stable ref per node:

  button "Save changes" ref=e7
* textbox "Email" ref=e3 [value=""]
  [scrollable "Results" y=0/1840 ref=e12]

The agent then acts on the ref - browser(action:'click', ref:'e7') - instead of guessing CSS selectors from source. A * marks elements new since the last snapshot, which is how the agent confirms what a click actually did without paying for a screenshot.

Desktop extras

The desktop's Chromium adds the DevTools tier:

audit - Core Web Vitals, page weight, a11y and SEO checks, horizontal-overflow detection
throttle - slow-3g/4g/offline network emulation plus CPU slowdown
network_start / network_stop - record every request (status, size, timing, failures)
run_server / stop_server / list_servers - start dev servers from .empryo/launch.json and open them in a tab
A visible, tabbed panel you share with the agent - tab leases keep two agents from typing into one page (see tabs)

Terminal browser

On the TUI and in --headless runs the same tool drives a headless system webview: WKWebView on macOS, WebView2 on Windows, Chrome/Chromium on Linux (install one, or point BUN_CHROME_PATH at it - without a Chrome the tool simply is not offered). Screenshots come back to the model as images, which is how the page is "seen" without a panel.

Turn it off entirely with "terminalBrowser": false in config.

Config

Key	Default	Effect
`terminalBrowser`	on where available	The browser tool on TUI + headless
`terminalBrowserAllowExternal`	`false`	Allow public-internet URLs in the terminal browser