Configure the browser

The Browser (kind: "web") is a web browser H provisions per session in the cloud, or Chrome on your own machine with local control. Reference a built-in browser by catalog name (like "h/browser"), or define one inline in an agent’s environments list. Inline, only id is required. Every other field has a default.

Fields

Field	Default	Meaning
`id`	required	Catalog identifier.
`kind`	`"web"`	Environment type. A browser is `web`.
`start_url`	`"https://www.bing.com"`	First URL to open.
`headless`	`false`	Run without a visible window.
`mode`	`{"type": "visual"}`	How the agent sees and acts: `visual` or `text`. See Modes.
`lazy`	`false`	Cloud only. Start the browser on the agent’s first browser action, not at session start. The first turn gets no initial page observation, and an unused browser never starts. Actions are the same.
`settle_s`	`1.0`	Seconds the agent waits after each action, so the next observation shows the settled page. `0` to `10`.
`host`	`"cloud"`	`cloud` (H infrastructure) or `user_device` (Chrome on your machine, see Local control).
`session_id`	`null`	Command channel of a `user_device` browser. The Python SDK sets it. Set it yourself only to attach to `hai local browser`.

These apply to cloud browsers only.

Field	Default	Meaning
`vault_id`	`null`	Vault whose secrets the agent can fill into login forms. Must be in your organization.
`browser_profile_id`	`null`	Browser profile to load (cookies, storage), so the session starts signed in. Must be in your organization.
`use_default_browser_profile`	`false`	Load your default profile (created empty on first use) and save state back when the session ends. Mutually exclusive with `browser_profile_id`.
`persist_browser_profile`	`false`	Save the final state back into the loaded profile. Requires `browser_profile_id` or `use_default_browser_profile`. Best-effort: a profile has one writer, and other sessions start read-only. See Persisting state back.
`network`	`null`	Proxy egress: `managed_proxy` or `proxy_url`, set only one. See Proxy.

Modes

At each step the agent gets a fresh observation of the page, then picks one or more actions. mode sets what the observation contains and which actions exist.

Mode	The agent sees	The agent acts	Use it for
`visual` (default)	A viewport screenshot, the URL, and open tabs. With `markdown: true`, also the page text.	Points at on-screen targets, and the platform resolves exact click and type coordinates.	General web work: clicking, forms, anything that needs the rendered page.
`text`	The page as text only, split into chunks of `chunk_size` characters.	Reads, pages through chunks, follows links by URL. Read-only: it cannot click or type.	Reading and research at scale: search, scraping, link-heavy navigation.

Cost tracks screenshots. text sends no images, so it uses the fewest tokens and runs fastest. markdown: true adds the page text on top of each screenshot. Default to visual, and switch to text for pure reading.
text mode pages instead of scrolling. Each observation says which chunk the agent is on. Raise chunk_size to fit more per step, at more tokens per observation.
Replay what the agent saw. Every observation is on the event stream: web in visual mode, textual_web in text mode.

Mode fields

mode is an object selected by type, carrying only the fields of that mode.

`type`	Field	Default	Meaning
`visual`	`width`	`1200`	Viewport width in pixels. Positive integer. Cloud only: a `user_device` browser keeps its window’s size.
`visual`	`height`	`1200`	Viewport height in pixels. Positive integer. Cloud only: a `user_device` browser keeps its window’s size.
`visual`	`markdown`	`false`	Also include the viewport’s text as markdown with each screenshot.
`text`	`chunk_size`	`20000`	Characters of page text per chunk. Positive integer.

Text-mode browser

{ "id": "research-browser", "kind": "web", "mode": { "type": "text", "chunk_size": 20000 } }

Actions

The agent picks actions on its own. You never call them, and there is no per-agent tool list. To shape how it uses them, set the agent’s instructions.

Action	Description	Visual	Text
`go_to_web`	Navigate to a URL.	✓	✓
`go_back_web`	Go back in the browser history.	✓	✓
`refresh_web`	Refresh the current page.	✓	✓
`switch_tab_web`	Switch to another tab, or open a new one.	✓	✓
`close_tab_web`	Close a tab.	✓	✓
`click_web`	Click at viewport coordinates.	✓
`write`	Focus an input at coordinates and type into it.	✓
`fill_secret_at`	Fill a vault secret (like `password` or `totp`) into a field. The value goes straight into the page, never into the agent’s context. Offered only when a vault is bound via `vault_id` and matches the current page.	✓
`select_option`	Pick an option from a native `<select>` dropdown.	✓
`move_mouse_web`	Move the mouse to reveal hovers, tooltips, or menus.	✓
`press_keys_web`	Press keys or keyboard shortcuts.	✓
`scroll_web`	Scroll the page or a nested scrollable container.	✓
`ctrl_f_web`	Jump to the next on-page match of a text query.	✓
`reader_mode`	Extract the page’s main content as clean markdown.	✓
`find_in_page`	Find a text query and jump to the chunk that contains it.		✓
`switch_chunk`	Page forward or backward through the page’s text chunks.		✓
`wait_web`	Pause for the page to settle (up to 60 seconds).	✓	✓

Related: Profiles, Proxy, Vaults.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Fields

Modes

Mode fields

Actions

​Fields

​Sign-in and network fields

​Modes

​Mode fields

​Actions

Fields

Sign-in and network fields

Modes

Mode fields

Actions