Skip to main content
Skyvern uses Playwright with Chromium to execute browser automations.

​
Browser modes

The BROWSER_TYPE setting controls how Skyvern runs the browser.

​
Headful (default)

.env
BROWSER_TYPE=chromium-headful
The browser runs with a visible window. In Docker, this displays on a virtual framebuffer (Xvfb).

​
Headless

.env
BROWSER_TYPE=chromium-headless
The browser runs without any display.
Some websites detect and block headless browsers. If you encounter issues with bot detection, try headful mode with a virtual display.

​
CDP Connect (External Chrome)

.env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
Connect to an existing Chrome instance running with remote debugging enabled. Useful for:
  • Using your existing browser profile with saved logins
  • Debugging with Chrome DevTools
  • Running automations on a browser with specific extensions

​
Setting up CDP Connect

CDP (Chrome DevTools Protocol) lets Skyvern control an external Chrome browser instead of launching its own.

​
Step 1: Start Chrome with remote debugging

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/chrome-cdp-profile" \
  --no-first-run \
  --no-default-browser-check
The --user-data-dir flag creates a separate profile for Skyvern, preserving your main Chrome profile.

​
Step 2: Configure Skyvern

.env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
When running Skyvern in Docker:
Host OSURL
macOS/Windowshttp://host.docker.internal:9222/
Linuxhttp://172.17.0.1:9222/

​
Step 3: Verify connection

Test that Skyvern can reach Chrome: 
curl http://localhost:9222/json/version
You should see Chrome’s version information.
CDP mode exposes Chrome to network access. Only use this in trusted environments and bind to localhost when possible.

​
Display settings

Configure how the browser appears to websites. These settings affect geolocation detection and content rendering.

​
Locale and timezone

.env
# Optional, unset by default. Set to match your target region.
BROWSER_LOCALE=en-US
BROWSER_TIMEZONE=America/New_York
Set these to match your target audience or the expected user location. Mismatched locale/timezone can trigger bot detection on some sites. Common combinations:
RegionBROWSER_LOCALEBROWSER_TIMEZONE
US Easten-USAmerica/New_York
US Westen-USAmerica/Los_Angeles
UKen-GBEurope/London
Germanyde-DEEurope/Berlin
Japanja-JPAsia/Tokyo

​
Viewport size

.env
BROWSER_WIDTH=1920
BROWSER_HEIGHT=1080
The default 1920x1080 works for most sites.

​
Timeout settings

Control how long Skyvern waits for various browser operations.
.env
# Time to wait for individual actions (clicks, typing)
BROWSER_ACTION_TIMEOUT_MS=5000

# Time to wait for screenshots to capture
BROWSER_SCREENSHOT_TIMEOUT_MS=20000

# Time to wait for page loads
BROWSER_LOADING_TIMEOUT_MS=60000

# Time to wait for DOM tree analysis
BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS=60000

​
When to adjust timeouts

SymptomAdjustment
Actions fail on slow sitesIncrease BROWSER_ACTION_TIMEOUT_MS
Screenshots timeout on complex pagesIncrease BROWSER_SCREENSHOT_TIMEOUT_MS
Page load timeoutsIncrease BROWSER_LOADING_TIMEOUT_MS
DOM analysis fails on large pagesIncrease BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS

​
Advanced settings

​
Browser logging

.env
BROWSER_LOGS_ENABLED=true
When enabled, browser console logs are captured in artifacts. Useful for debugging JavaScript errors on target sites.

​
Maximum pages

.env
BROWSER_MAX_PAGES_NUMBER=10
Limits the number of browser tabs Skyvern can open simultaneously. Increase if your workflows navigate multiple pages in parallel; decrease to reduce memory usage.

​
Chrome policies

.env
BROWSER_POLICY_FILE=/etc/chromium/policies/managed/policies.json
Path to a Chrome policy file for enterprise configurations.

​
Video recording path

.env
VIDEO_PATH=./videos
Directory where browser session recordings are saved. Recordings are useful for debugging but consume disk space.

​
Memory considerations

Browser instances are memory-intensive. These are approximate guidelines. Actual usage depends on page complexity and browser settings.
Concurrent tasksRecommended RAM
1-24GB
3-58GB
6-1016GB
10+32GB+
If you experience out-of-memory errors:
  1. Reduce BROWSER_MAX_PAGES_NUMBER
  2. Use a smaller viewport (BROWSER_WIDTH, BROWSER_HEIGHT)
  3. Run in headless mode (BROWSER_TYPE=chromium-headless)
  4. Limit concurrent task execution

​
Scaling browsers

The default Docker Compose setup runs one browser instance inside the Skyvern container. For higher concurrency:

​
Option 1: Vertical scaling

Add more RAM to your server and increase MAX_STEPS_PER_RUN and BROWSER_MAX_PAGES_NUMBER.

​
Option 2: Horizontal scaling

Deploy multiple Skyvern instances behind a load balancer. Each instance runs its own browser. See Kubernetes Deployment for orchestrated scaling.

​
Option 3: External browser pool

Use a browser pool service like Browserless or your own Playwright grid, then connect via CDP:
.env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://browserless:3000/

​
Next steps

Proxy Setup

Configure proxies to avoid bot detection

Storage Configuration

Store recordings and artifacts in S3 or Azure Blob