Configure the browser

The Browser (kind: "web") is the environment H ships today: a managed web browser the platform provisions per session, or, with local control, Chrome on your own machine. Reference a built-in browser by catalog name (like "h/browser"), or define one inline in an agent’s environments list. When you define a Browser inline, only id is required; every other field has a default. Reference a catalog entry instead and it supplies them for you.

Field	Default	Description
`id`	required	Catalog identifier for the environment.
`kind`	`"web"`	Environment type; a browser is `web`.
`start_url`	`"https://www.bing.com"`	Initial URL to open.
`headless`	`false`	Run the browser without a visible window.
`mode`	`{"type": "visual"}`	How the agent perceives and drives the browser. An object keyed by `type` (`visual` or `text`); see Modes.
`vault_id`	`null`	Id of a vault to bind to this browser, letting the agent sign in to sites with secrets resolved from the vault. Must reference a vault in your organization. Cloud-hosted browsers only. Omit to run without secret access.
`browser_profile_id`	`null`	Id of a browser profile to load into this browser, restoring saved cookies and storage so the agent starts the session already signed in. Must reference a profile in your organization. Cloud-hosted browsers only. Omit to start with a fresh profile.
`use_default_browser_profile`	`false`	Load your default browser profile for this browser instead of naming one, auto-creating an empty one on first use. The session saves its final state back automatically when it ends (best-effort: concurrent sessions run read-only). Mutually exclusive with `browser_profile_id`. Cloud-hosted browsers only.
`persist_browser_profile`	`false`	Save the session’s final browser state (cookies, storage) back into the loaded profile when it ends. Requires `browser_profile_id` or `use_default_browser_profile`. Best-effort: only one active session at a time may persist a given profile — if another writer is active, the session starts read-only instead of failing. See Persisting state back.
`network`	`null`	Network settings for the session. Holds `managed_proxy` to have H provision a proxy for the browser’s egress, or `proxy_url` to route through your own (set only one). Applied when a cloud browser session is provisioned. See Proxy.
`host`	`"cloud"`	Where the browser runs: `cloud` on H infrastructure, or `user_device` for Chrome on your own machine. See Local browser.
`session_id`	`null`	Id of the command channel a `user_device` browser is served on. The Python SDK sets it when it starts the connection for you; set it yourself only to attach to one you run with `hai local browser`.

Modes

At each step the agent receives a fresh observation of the page, then chooses one action. The mode field sets what that observation contains and which actions are on the table.

Mode	What the agent sees	How it acts	Reach for it when
`visual` (default)	A screenshot of the viewport (`1200×1200` by default), with the current URL and open tabs. Set `markdown: true` to also include the page’s text in the same observation.	Points at on-screen targets; the platform resolves each one to exact click and type coordinates.	General web work: clicking, filling forms, anything that needs the rendered page.
`text`	The page as text only, no screenshot, split into chunks of about `chunk_size` characters (`20000` by default).	Reads and pages through the chunks and follows links by URL. Read-only: no clicking or typing.	Reading and research at scale: search, scraping, link-heavy navigation.

Cost and speed track the screenshots. text mode sends no images, so it uses the fewest tokens and runs fastest; visual sends a screenshot every step, and markdown: true adds the full page text on top of it. Default to visual, and switch to text when the task is pure reading.
text mode pages through long content. Rather than scrolling, the page is cut into chunk_size-sized chunks; the agent moves between them and each observation tells it which chunk it is on. Raise chunk_size to fit more per step, at the cost of more tokens per observation.
Watch what the agent saw. Every observation rides the event stream, as a web observation in visual mode and a textual_web observation in text mode, so you can replay each step exactly as the agent perceived it.

Mode fields

mode is an object selected by type. Each shape carries only the fields that apply to it, so illegal combinations cannot be expressed. visual (default) renders screenshots and acts by viewport coordinates:

Field	Default	Description
`type`	`"visual"`	Selects visual mode.
`width`	`1200`	Viewport width in pixels. Must be a positive integer.
`height`	`1200`	Viewport height in pixels. Must be a positive integer.
`markdown`	`false`	Also include the viewport’s text as markdown alongside each screenshot.

text serves read-only paginated markdown with no screenshots:

Field	Default	Description
`type`	`"text"`	Selects text mode.
`chunk_size`	`20000`	Characters of page text shown per page. Must be a positive integer.

Text-mode browser

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

Actions

Each mode fixes the set of actions available to the agent. It chooses them autonomously as it works; you never call them directly and there is no per-agent tool list to configure. 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-resolved secret (e.g. `password`, `totp`) into a field at coordinates so the agent can sign in on your behalf. The value is injected directly into the page and never enters the agent’s context. Offered only when a vault is bound to the browser via `vault_id` and can match a credential for 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).	✓	✓

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Configure the browser

Modes

Mode fields

Actions

Next steps

Profiles

Proxy

​Modes

​Mode fields

​Actions

​Next steps

Profiles

Proxy

Modes

Mode fields

Actions

Next steps