> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Browser descriptor

> Reference for the `Browser descriptor` schema.

## Referenced In

* [startSurface](/reference/schemas/startsurface)

## Fields

| Field         | Type                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default |
| :------------ | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| browser       | string                                                                    | Required. Browser engine to open. The session opens on the context's automation server with a blank page and registers as a surface; use a goTo step (with `surface`) to navigate it. No cross-engine fallback — the one exception is `edge`, which is Chromium and opens on the same Chrome/chromedriver stack (it registers under the `chrome` engine, and defaults its surface name to `chrome` when you don't set one). Accepted values: `chrome`, `firefox`, `safari`, `webkit`, `edge` | —       |
| name          | string                                                                    | Optional. Surface-registry name later steps use in `surface`. Default: the engine name. Must be unique across all open surfaces — the context's default browser already owns its engine name, so name a second same-engine session explicitly. An engine keyword may only name a session of that engine. Minimum length: 1. Pattern: `\S`                                                                                                                                                    | —       |
| headless      | boolean                                                                   | Optional. Run this session headless. Default: the context's browser headless setting.                                                                                                                                                                                                                                                                                                                                                                                                        | —       |
| size          | object([Browser window size](/reference/schemas/browser-window-size))     | Optional. Outer window dimensions for this session. Default: the context's browser window size.                                                                                                                                                                                                                                                                                                                                                                                              | —       |
| viewport      | object([Browser viewport size](/reference/schemas/browser-viewport-size)) | Optional. Viewport (page-content) dimensions for this session; the window is resized so the content area matches. Takes precedence over `size` when both are set.                                                                                                                                                                                                                                                                                                                            | —       |
| driverOptions | object                                                                    | Optional. Escape-hatch passthrough: merged into the session's capabilities after the ones Doc Detective computes. Driver- and version-specific; use sparingly.                                                                                                                                                                                                                                                                                                                               | —       |

## Examples

```json
{
  "browser": "chrome",
  "name": "example",
  "headless": true,
  "size": {
    "width": 42,
    "height": 42
  },
  "viewport": {
    "width": 42,
    "height": 42
  },
  "driverOptions": {}
}
```