Browser configuration
Set language, timezone, location, viewport, and browser mode.
With an initialized TypeScript client:
await client.withSession({
viewport: { width: 1280, height: 800 },
browser: {
locale: "en-US",
timezone: "Asia/Tokyo",
headless: true,
geolocation: { latitude: 35.68, longitude: 139.69 },
permissions: [{ origin: "https://example.com", permissions: ["geolocation"] }],
},
}, async (session) => {
// Connect to session.id using your browser client.
});Python uses the same nested browser fields with client.with_session(browser={...}).
| Parameter | Type | Default / limits |
|---|---|---|
browser.locale | string | Browser default; valid BCP 47 language tag |
browser.timezone | string | UTC; valid IANA timezone |
browser.userAgent | string | Chromium default; 1–512 printable ASCII characters |
browser.headless | boolean | true; Live view works in both modes |
browser.geolocation | object | Latitude −90…90, longitude −180…180; accuracy 0…100,000 metres, default 0 |
browser.permissions | array | Up to 20 explicit HTTP(S) origins and their permissions |
browser.extensions | array | Supported ID: block-images |
viewport | object | Width and height each 320–4,096 pixels; instance default |
metadata | string map | Up to 10 entries; key ≤64, value ≤256 characters |
Allowed permissions: geolocation, notifications, clipboard-read, clipboard-write. An origin has no path, for example https://app.example.com. Geolocation requires a secure website and permission for that origin.
Settings apply when the browser starts, including new tabs and popups. They are fixed for the session. Configured sessions start fresh instead of using the default warm pool.
Extensions
const session = await client.sessions.create({
browser: { extensions: ["block-images"] },
});block-images blocks image network requests. Unknown IDs, duplicate IDs, URLs, and filesystem paths are rejected. Customer extension uploads are not part of this interface.
Region chooses placement. Timezone changes page-visible time. Proxy settings concern network egress. Metadata identifies your task; your backend still authorizes users.