> ## Documentation Index > Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configure the browser > Define a Browser environment: its fields, modes, and actions. The Browser (`kind: "web"`) is the environment H ships today: a managed web browser the platform provisions per session, or, with [local control](/computer-use-agents/browser/local-control), Chrome on your own machine. Reference a [built-in browser](/computer-use-agents/environments/overview#built-in-environments) 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](#modes). | | `vault_id` | `null` | Id of a [vault](/computer-use-agents/vaults/overview) 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](/computer-use-agents/browser/profiles) 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](/computer-use-agents/browser/profiles#default-profiles) 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](/computer-use-agents/browser/profiles#persisting-state-back-into-the-profile). | | `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](/computer-use-agents/browser/proxy). | | `host` | `"cloud"` | Where the browser runs: `cloud` on H infrastructure, or `user_device` for Chrome on your own machine. See [Local browser](/computer-use-agents/browser/local-control). | | `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`](/computer-use-agents/browser/local-control#run-a-session). | ## 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](#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](/computer-use-agents/sessions/events#observation-shapes), 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. | ```json Text-mode browser theme={null} { "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`](/computer-use-agents/agents/overview). | 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](/computer-use-agents/vaults/overview) 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 `