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 — visible browser window (default)
  • Headless — no display, runs in the background
  • Use Your Own Chrome — runs the installed Chrome app with your logged-in profile
  • CDP Connect — connects to an already-running Chrome instance

​
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.

​
Use Your Own Chrome

.env
BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Skyvern launches the Chrome app installed on your machine and connects to it automatically. Your existing Chrome profile (cookies, saved logins, extensions) is copied over so automations run in a browser environment that matches your real one. Useful for:
  • Running automations with your saved logins and cookies
  • Using your installed Chrome extensions
  • Avoiding bot detection by using a real Chrome installation

​
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 Use Your Own Chrome

Set CHROME_EXECUTABLE_PATH to your Chrome installation path and Skyvern handles the rest — no need to manually start Chrome with debugging flags.

​
Step 1: Find your Chrome path

/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

​
Step 2: Configure Skyvern

BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
When Skyvern starts, it will:
  1. Copy your Chrome profile to a working directory (./tmp/user_data_dir)
  2. Launch Chrome with remote debugging on port 9222
  3. Connect via CDP automatically
All existing Chrome windows must be closed before Skyvern can launch Chrome with remote debugging. If Chrome is already running, Skyvern will return an error.
If port 9222 is already in use (e.g., from a previous session), Skyvern will connect to the existing instance instead of launching a new one.

​
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