Built-in Browser (Desktop Browser)

Since v0.8.7, the Windows desktop app ships a sidebar Browser view: open pages in-app and let the agent drive them with browser_* tools.

Desktop only. zagens-tui / CLI have no Browser host. Agent calls return browser_host_missing until you open the Browser view in the desktop app.

How to open

Entry	Notes
Icon rail Browser	Opens the Browser panel
Ctrl+Shift+B	Shortcut to open and focus
http(s) links in chat	Open in-app by default; right-click for system browser

Address bar: back / forward / reload. Embed mode: auto (prefer embed) / sidebar embed / separate window.

Agent tools

Tool	Purpose
`browser_navigate`	Go to a URL (loopback auto; external hosts ask approval)
`browser_snapshot`	Visible text + a11y tree; stable refs (`role:slug:nth`); optional screenshot
`browser_get_text`	Title + visible text (snapshot subset)
`browser_console_tail`	Console buffer (cleared on navigation)
`browser_click` / `browser_type` / `browser_scroll`	Interact by snapshot `ref` (approval by default)
`browser_wait`	Wait for `text` / `ref` / `selector` / `load`
`browser_start_preview`	Read workspace `.zagens/preview.json`, start local server, navigate

Typical flow: browser_navigate → browser_wait → browser_snapshot → click/type by ref.

Approvals and YOLO

External browser_navigate: approval card by default; approve may add a session host allowlist.
Loopback (localhost / 127.0.0.1) and workspace file://: usually skip external-nav ask.
Click / type / scroll: ask by default — independent of global “auto-approve tools”.
browser_yolo: relaxes Browser write actions only — panel toggle, [browser] yolo in ~/.zagens/config.toml, or ZAGENS_BROWSER_YOLO.

Prefs live in ~/.zagens/browser/prefs.json (legacy AppData path migrates on first read).

Local preview (`.zagens/preview.json`)

{
  "command": "npm run dev",
  "cwd": ".",
  "url": "http://127.0.0.1:5173",
  "ready_pattern": "Local:"
}

Use Start preview.json in the panel or browser_start_preview: spawn → wait for ready_pattern (optional ready_regex) → navigate to url.

vs fetch / web.run

	Built-in Browser	`fetch_url` / `web.run`
Host	Desktop Browser pane	Runtime HTTP fetch
Interaction	Click, type, wait for DOM	No real page control
Local SPA	Good for localhost preview	Not for driving a frontend

Use Web tools for search/fetch; use this page for real browser control.

Tips

On browser_host_missing, open the Browser view first.
Review approval policy before external automation; avoid casual browser_yolo.
Static HTML preview: File preview; interactive sites: Browser.

Related: File preview · Web tools · Tool approval · UI tour