# Browser Options

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

The `new_session` tool accepts `browser_options` to control viewport, emulation, extensions, and more. Your AI coding agent uses these parameters automatically based on your instructions.

## All Browser Options

| Option              | Type      | Description                                                       | Default    |
| ------------------- | --------- | ----------------------------------------------------------------- | ---------- |
| `viewport`          | `object`  | `{ width, height }` in pixels                                     | 1280 × 720 |
| `is_mobile`         | `boolean` | Emulate mobile device behavior (CSS media queries, meta viewport) | `false`    |
| `has_touch`         | `boolean` | Enable touch events                                               | `false`    |
| `user_agent`        | `string`  | Custom user agent string                                          | —          |
| `color_scheme`      | `string`  | `"light"`, `"dark"`, or `"no-preference"`                         | `"light"`  |
| `timezone_id`       | `string`  | Timezone ID (e.g., `"America/New_York"`)                          | —          |
| `geolocation`       | `object`  | `{ latitude, longitude, accuracy? }`                              | —          |
| `locale`            | `string`  | Browser locale (e.g., `"en-US"`, `"ja-JP"`)                       | —          |
| `disable_security`  | `boolean` | Disable web security (CORS, CSP)                                  | `false`    |
| `record_evidence`   | `boolean` | Enable video and trace recording                                  | `false`    |
| `headless`          | `boolean` | Run browser in headless mode                                      | `false`    |
| `proxy`             | `object`  | `{ server, username?, password? }`                                | —          |
| `path_to_extension` | `string`  | Path to unpacked Chrome extension directory                       | —          |
| `user_data_dir`     | `string`  | Chrome user data directory for persistent profile                 | —          |

## Top-Level Options

These are passed alongside `browser_options`, not inside it:

| Option               | Type     | Description                                                     |
| -------------------- | -------- | --------------------------------------------------------------- |
| `starting_url`       | `string` | URL to navigate to on session creation (default: `about:blank`) |
| `storage_state_path` | `string` | Path to storage state file to restore cookies/localStorage      |

## Usage Examples

Tell your coding agent to start a session with specific options:

```
Open a browser at localhost:3000 with a mobile viewport (390x844)
and touch enabled
```

```
Start a browser session with video recording and verify the checkout flow
```

```
Open a browser with my Chrome extension at ./my-extension
and navigate to https://example.com
```

```
/verify airbnb.com shows Japanese UI with locale ja-JP
and timezone Asia/Tokyo
```

```
Open a browser using the Chrome profile at ./chrome-profile
and verify my saved login still works
```