> ## Documentation Index > Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt > Use this file to discover all available pages before exploring further. # SDK browser reference > Reference managed browser lifecycle methods, browser handles, resources, advanced browser-code execution, capture options, signed URLs, and lifecycle responses. `web.browser` manages persistent cloud browsers. Use it when you need deterministic code around a browser session, or when an agent workflow needs setup, teardown, downloads, recordings, or inspection. ```ts theme={null} const browserAgent = web.agent({ model, approval: "ask", }); const browser = await web.browser.create({ recording: true, policy: { allowedDomains: ["vendor.example"] }, }); const result = await browserAgent.run({ browserId: browser.id, startUrl: "https://vendor.example/dashboard", goal: "Find the latest paid invoice and download the PDF.", }); const downloads = await browser.downloads.list(); ``` When you pass `browserId`, put browser policy on `web.browser.create(...)`; do not also configure `browser.policy` on that agent. ## `WebBrowserResource` ```ts theme={null} interface WebBrowserResource { create( options?: BrowserCreateOptions, request?: { signal?: AbortSignal; idempotencyKey?: string; timeoutMs?: number } ): Promise; get(id: BrowserId | string, request?: { signal?: AbortSignal }): Promise; list(options?: BrowserListOptions): Promise; connect(id: BrowserId | string): Promise; } ``` | Method | Description | | --------- | --------------------------------------------------- | | `create` | Create a new browser. | | `get` | Fetch browser metadata and return a browser handle. | | `list` | List browsers with pagination and filters. | | `connect` | Return a browser handle for an existing browser. | ## `BrowserCreateOptions` | Field | Type | Default | Description | | ------------- | ------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `proxy` | `string` | None | Proxy URL for browser traffic, for example `http://user:pass@proxy.example:8080`. Blank values are omitted by the SDK. | | `maxDuration` | `number` | `86400000` | Maximum browser duration in milliseconds. | | `recording` | `boolean` | `false` | Enables recording for the browser. | | `policy` | `BrowserNavigationPolicy` | Client-level policy, if configured | Browser navigation and operation-control policy. | ## `BrowserListOptions` | Field | Type | Description | | --------------- | ---------------------------------- | --------------------------- | | `status` | `BrowserStatus \| BrowserStatus[]` | Filter by lifecycle status. | | `limit` | `number` | Results per page. | | `cursor` | `string` | Pagination cursor. | | `createdAfter` | `string` | ISO timestamp lower bound. | | `createdBefore` | `string` | ISO timestamp upper bound. | | `signal` | `AbortSignal` | Abort the request. | `BrowserListResponse` contains `items`, `limit`, `hasMore`, and `nextCursor`. ## `Browser` ```ts theme={null} interface Browser { readonly id: BrowserId; readonly lifecycleStatus?: BrowserStatus; readonly readiness?: unknown; readonly capabilities?: BrowserCapabilityAvailability; readonly metadata?: Record; readonly createdAt?: string; readonly updatedAt?: string; readonly stoppedAt?: string; readonly retentionExpiresAt?: string; readonly recording?: unknown; readonly errorMessage?: string | null; playwright: BrowserPlaywright; files: BrowserFiles; downloads: BrowserDownloads; dialogs: BrowserDialogs; permissions: BrowserPermissions; recordings: BrowserRecordings; captcha: BrowserCaptcha; status(options?: BrowserStatusOptions): Promise; events(options?: BrowserEventsOptions): Promise; streamEvents(options?: BrowserEventStreamOptions): AsyncIterable; pages(options?: { cursor?: string; limit?: number; signal?: AbortSignal }): Promise; cdpUrl(): Promise; debugUrl(): Promise; stop(options?: { signal?: AbortSignal; idempotencyKey?: string }): Promise; resume(options?: { signal?: AbortSignal; idempotencyKey?: string }): Promise; close(options?: { signal?: AbortSignal; idempotencyKey?: string }): Promise; } ``` ## Lifecycle methods | Method | Description | | ------------------ | --------------------------------------------------------------------------------------------------------- | | `browser.status()` | Fetch compact runtime status: active tab, tabs, cookies, last action, blockers, and next action metadata. | | `browser.pages()` | List page summaries with `id`, `browserId`, `url`, `title`, and `active`. | | `browser.stop()` | Stop the browser while retaining recoverable state. | | `browser.resume()` | Resume a stopped browser. | | `browser.close()` | Close the browser. | Lifecycle responses include browser metadata and may include `_meta`: | Field | Description | | ------------------ | -------------------------------------------- | | `_meta.poolHit` | Whether a warm-pool browser was used. | | `_meta.creationMs` | Gateway-level creation time in milliseconds. | ## Signed capability URLs | Method | Description | | -------------------- | ----------------------------------------------------- | | `browser.cdpUrl()` | Mint a signed Chrome DevTools Protocol WebSocket URL. | | `browser.debugUrl()` | Mint a signed Debug UI URL. | CDP and Debug UI URLs are bearer capabilities. Treat them like credentials until they expire. ## Advanced browser-code execution Use `browser.playwright.execute(...)` when a specific browser step must be exact. For most browser-agent workflows, create or fetch a browser handle and pass `browserId` into `agent.run(...)`. ```ts theme={null} const result = await browser.playwright.execute({ code: ` await page.goto("https://example.com"); return await page.title(); `, timeoutMs: 30_000, capture: { status: true, screenshot: "on_error", observation: { kind: "aria", depth: 5, maxChars: 20_000, }, }, }); ``` ```ts theme={null} interface BrowserPlaywright { execute( request: BrowserPlaywrightExecuteRequest, options?: { signal?: AbortSignal } ): Promise; } ``` Important execution rules: | Rule | Reason | | ----------------------------------- | ----------------------------------------------------------------------------- | | `page` is already in scope. | Snippets should use the active page instead of creating ordinary extra pages. | | Return values must be serializable. | The response includes the returned value in `result`. | | Omit `pageId` for active-page work. | `pageId` is for a known non-active page returned by Webcompute metadata. | | Use bounded timeouts. | Long browser operations should be explicit and observable. | Common request fields: | Field | Type | Description | | ----------- | ----------------- | -------------------------------------------- | | `code` | `string` | Top-level async browser-code body. Required. | | `pageId` | `PageId` | Optional target page ID. | | `timeoutMs` | `number` | Execution timeout in milliseconds. | | `capture` | `false \| object` | Capture controls. | Common response fields: | Field | Description | | ------------- | ---------------------------------------------------------------- | | `executionId` | Execution identifier. | | `success` | Whether the code completed successfully. | | `result` | Serialized return value when present. | | `error` | Structured error when execution failed. | | `logs` | Console logs captured during execution. | | `page` | Current page metadata. | | `status` | Compact runtime status when requested. | | `observation` | Bounded page observation when requested. | | `artifacts` | Screenshot, recording, or generated-file metadata when produced. | | `elapsedMs` | Browser-side elapsed time. | ## Capture options | Field | Type | Description | | ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | `screenshot` | `"never" \| "on_error" \| "always"` | Screenshot capture behavior. | | `status` | `boolean` | Include compact runtime status. | | `activity` | `boolean \| object` | Include passive page/navigation activity. Object fields include `maxPages` and `maxNavigationsPerPage`. | | `observation` | `boolean \| object` | Include bounded post-step observation. | Observation object fields: | Field | Description | | ----------- | -------------------------------------------- | | `enabled` | Enable or disable observation. | | `kind` | Observation kind: `aria`, `text`, or `none`. | | `locator` | Optional locator to scope observation. | | `depth` | ARIA observation depth. | | `boxes` | Include element boxes when supported. | | `timeoutMs` | Observation timeout. | | `maxChars` | Maximum returned observation characters. | | `includeOn` | Controls when observation is included. |