Skip to main content
Browserbase’s Advanced Stealth Mode is a real browser and has real browser fingerprints that provide significantly higher success rates than randomly generated configurations. This guide shows you how to customize OS and viewport settings for optimal results.

​
Customization Options

Advanced Stealth Mode offers three configuration options:
  1. Default: Windows OS with 2560x1440 viewport
    • For general automation use
  2. OS Only: Choose your OS (Linux, Windows, Mac)
    • Viewport size automatically optimized
  3. OS and Viewport: Specify both OS and viewport
    • For exact fingerprint control

​
Operating System Configuration

Specify the operating system and let Browserbase automatically optimize the viewport settings for that OS.
  • Node.js
  • Python
SDK
import Browserbase from "@browserbasehq/sdk";

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

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: {
    advancedStealth: true,
    os: "mac", // Auto-defaults to 2560x1440
  },
  proxies: true,
});
When using contexts, changing the os or viewport could reduce the success rate of your automation.

​
OS Default Viewports

When you specify only the Operating System, these are the automatic viewport defaults:
OSDefault ViewportUse Case
linux2560x1440High-res desktop automation
windows2560x1440Windows-specific testing
mac2560x1440macOS automation
mobile696x384Mobile app testing
tablet800x1112Tablet responsive testing

​
Custom Viewport Configuration

For precise control, specify both OS and viewport dimensions:
  • Node.js
  • Python
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: {
    advancedStealth: true,
    os: "windows",
    viewport: { 
      width: 1920, 
      height: 1080,
    },
  },
  proxies: true,
});

​
Supported Viewport Combinations

  • 1728x1117 - MacBook Air 13”
  • 1800x1169 - MacBook Pro 13”
  • 2560x1440 - MacBook Pro 16”
  • 3840x1080 - Ultra-wide display
  • 1920x1080 - Full HD
  • 2560x1440 - 2K display
  • 1920x1080 - Full HD
  • 2560x1440 - 2K display
  • 696x384 - Mobile devices
  • 800x1112 - Tablet devices

​
Error Handling & Validation

ScenarioResultDetails
advancedStealth: false + OSErrorCannot use OS without Advanced Stealth
Invalid OS valueErroros: "android" (not supported)
Invalid OS/viewport comboErrormac + 1920x1080
No OS specifiedWindows defaultFalls back to Windows + 2560x1440

​
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 OS Settings: For general automation, specify only the os parameter and let the system select optimal viewport defaults. This simplifies configuration while maintaining high success rates.

​
Viewport Configuration

  • Precise Dimensions: When pixel-perfect matching is required (e.g., UI testing), configure both os and viewport using the supported combinations listed above.
  • Mobile & Tablet Testing: Use mobile or tablet OS values with their corresponding viewports for testing responsive designs and mobile-specific features.

​
Maximizing Success Rate

  • Maintain Profile Integrity: Avoid modifying viewport dimensions or user agent strings through automation frameworks like Playwright. Our pre-made fingerprints are carefully crafted to work together as complete profiles.
  • Enable Proxies: Always pair Advanced Stealth Mode with our proxy infrastructure for optimal bot detection avoidance. The combination provides the highest success rates.

​
Implementation Tips

  • Validate Configurations: Implement proper error handling for invalid OS/viewport combinations to ensure graceful fallbacks in your automation scripts.
  • Monitor Success: Track your automation success rates and adjust OS/viewport combinations 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.