Skip to main content
Browserbase Verified sessions use a purpose-built browser with real browser fingerprints that are recognized by Browserbase’s bot protection partners. This guide shows you how to customize OS settings for optimal results.

​
Customization options

Verified offers two configuration options:
  1. Default: Automatically configured with a standard desktop fingerprint
    • For general automation use
  2. OS Selection: Choose your OS (Linux, Windows, Mac, Mobile, Tablet)
    • Changes the user agent and browser environment to match the selected platform

​
Operating system configuration

Specify the operating system to change the browser’s user agent and environment signals.
SDK
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({apiKey: process.env.BROWSERBASE_API_KEY!});

const session = await bb.sessions.create({
  browserSettings: {
    verified: true,
    os: "mac",
  },
  proxies: true,
});
When using contexts, changing the OS could reduce the success rate of your automation.

​
OS viewports

OSViewportUse Case
linux1280x720Desktop automation with Linux environment
windows1280x720Windows-specific testing
mac1280x720macOS automation
mobile384x696Mobile app testing
tablet800x1200Tablet responsive testing
Desktop platforms (Linux, Windows, Mac) all use a standardized viewport with a complete, pre-made fingerprint profile. Viewport customization is not available for Verified sessions - this ensures the highest possible success rates.Viewport dimensions listed above are approximate and may change at any time as Browserbase optimizes fingerprint profiles. Do not rely on specific viewport values in your automation logic.If your use case requires a specific custom viewport, disable Verified (verified: false) and configure the viewport directly. See the Viewports guide for configuration details.

​
Error handling and validation

ScenarioResultDetails
verified: false + OSErrorCannot use OS without Verified
Invalid OS valueErroros: "android" (not supported)
No OS specifiedDefault profileFalls back to the default desktop fingerprint

​
Best practices

​
Operating system selection

  • Match target environment: Choose an OS that aligns with your use case. For example, use windows when automating Windows-specific sites or testing Windows-only features.
  • Default for general use: For most automation tasks, simply enable verified: true without specifying an OS. The default profile is optimized for the highest success rates.

​
Mobile & tablet testing

  • Dedicated viewports: Use mobile or tablet OS values for testing responsive designs and mobile-specific features. These platforms use their own dedicated viewport sizes (384x696 for mobile, 800x1200 for tablet).

​
Maximizing success rate

  • Maintain profile integrity: Avoid modifying viewport dimensions or user agent strings through automation frameworks like Playwright. The pre-made fingerprints are carefully crafted to work together as complete profiles.
  • Enable proxies: Always pair Verified with the proxy infrastructure for the highest success rates.

​
Implementation tips

  • Monitor success: Track your automation success rates and adjust OS selections if you notice decreased performance on specific sites.
This feature is currently in beta; if you have any feedback, please reach out to support@browserbase.com.