Browser Options

View as Markdown

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