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/
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
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
Docker Compose self-host installs default BROWSER_STREAMING_MODE to cdp. Existing installs that already set this variable in .env keep their value. To opt out of CDP livestreaming, set BROWSER_STREAMING_MODE=vnc in .env.

​
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: Enable Chrome remote debugging

For an already-running Chrome profile, prefer Chrome’s built-in remote debugging toggle:
  1. Open chrome://inspect/#remote-debugging in Chrome.
  2. Enable remote debugging for this browser instance.
  3. Keep Chrome open while Skyvern connects.
This path keeps you on your existing Chrome profile. Skyvern will first try to auto-discover a local debugging server, then let you paste a direct ws://.../devtools/browser/... URL if Chrome exposes only a WebSocket endpoint.

​
Docker-reachable isolated profile fallback

When Skyvern runs in Docker, Chrome’s built-in listener may bind to host loopback only. If the container cannot reach it, start a separate Chrome profile with a Docker-reachable CDP endpoint: 
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --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. Since Chrome 136, --remote-debugging-port is ignored for the default Chrome data directory, so only use these flags with a non-standard user data directory.

​
Windows Docker Desktop with chrome://inspect

Chrome’s chrome://inspect/#remote-debugging toggle can bind its debugging server to host loopback only. Docker Desktop cannot connect to that listener directly through host.docker.internal. Skyvern includes a Windows helper that bridges Docker to Chrome and writes the exact WebSocket URL from Chrome’s DevToolsActivePort file. Open Chrome, go to chrome://inspect/#remote-debugging, enable remote debugging, then run this from an Administrator PowerShell in the Skyvern repo:
Windows
.\scripts\windows_chrome_inspect_cdp.ps1 -UpdateEnv
docker compose up -d --force-recreate skyvern
The helper creates a Windows port proxy from 0.0.0.0:9223 to Chrome’s loopback debugging port, adds a matching firewall rule, reads the full browser WebSocket path, and writes:
.env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=ws://host.docker.internal:9223/devtools/browser/<id>
BROWSER_REMOTE_DEBUGGING_HOST_HEADER=127.0.0.1:<chrome-port>
BROWSER_STREAMING_MODE=cdp
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
Chrome may prompt you to allow the remote debugging connection the first time Skyvern connects. Click Allow and retry the browser session if the first attempt times out.

​
Step 2: Configure Skyvern

.env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
Use the URL that matches the remote debugging path you chose. For a classic HTTP CDP endpoint, use the host and port. For a chrome://inspect flow that only exposes a browser WebSocket, use the full direct ws://.../devtools/browser/<id> URL. When running Skyvern in Docker:
Host OSURL
macOS/Windowshttp://host.docker.internal:9222/
Linuxhttp://172.17.0.1:9222/
If Docker Desktop reaches Chrome but Chrome rejects the host.docker.internal host name, Skyvern retries with the Docker host gateway IPv4 address. You can also set BROWSER_REMOTE_DEBUGGING_URL directly to that IPv4 address. If Windows Defender Firewall blocks the connection from Docker, allow inbound TCP traffic on port 9222:
Windows
New-NetFirewallRule -DisplayName "Chrome Remote Debug 9222" -Direction Inbound -LocalPort 9222 -Protocol TCP -Action Allow

​
Step 3: Verify connection

For a classic HTTP CDP endpoint, test that Chrome is listening on port 9222: 
curl http://localhost:9222/json/version
Windows
Invoke-RestMethod http://127.0.0.1:9222/json/version
You should see Chrome’s version information and a webSocketDebuggerUrl. If you used the Windows chrome://inspect helper, the configured URL is a direct ws://.../devtools/browser/<id> endpoint. In that mode, verify by starting a Skyvern browser session after restarting the backend.
If /json/version does not return Chrome version information from inside the Skyvern container, verify Chrome is listening on 0.0.0.0:9222 or ::9222 and that Windows Firewall allows inbound traffic on port 9222.
CDP mode exposes Chrome to network access. The examples use --remote-debugging-address=0.0.0.0 so Docker can reach Chrome on the host. Only use this in trusted environments. If Skyvern runs on the same host outside Docker, bind to 127.0.0.1 instead.

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