Browser Configuration

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

"C:\Program Files\Google\Chrome\Application\chrome.exe"

# Usually one of:
/usr/bin/google-chrome
/usr/bin/chromium
/usr/bin/chromium-browser

Step 2: Configure Skyvern

BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/usr/bin/google-chrome

When Skyvern starts, it will:

Copy your Chrome profile to a working directory (./tmp/user_data_dir)
Launch Chrome with remote debugging on port 9222
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:

Open chrome://inspect/#remote-debugging in Chrome.
Enable remote debugging for this browser instance.
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

"C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --remote-debugging-address=0.0.0.0 `
  --user-data-dir="C:\chrome-cdp-profile" `
  --no-first-run `
  --no-default-browser-check

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 OS	URL
macOS/Windows	`http://host.docker.internal:9222/`
Linux	`http://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:

Region	BROWSER_LOCALE	BROWSER_TIMEZONE
US East	`en-US`	`America/New_York`
US West	`en-US`	`America/Los_Angeles`
UK	`en-GB`	`Europe/London`
Germany	`de-DE`	`Europe/Berlin`
Japan	`ja-JP`	`Asia/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

Symptom	Adjustment
Actions fail on slow sites	Increase `BROWSER_ACTION_TIMEOUT_MS`
Screenshots timeout on complex pages	Increase `BROWSER_SCREENSHOT_TIMEOUT_MS`
Page load timeouts	Increase `BROWSER_LOADING_TIMEOUT_MS`
DOM analysis fails on large pages	Increase `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 tasks	Recommended RAM
1-2	4GB
3-5	8GB
6-10	16GB
10+	32GB+

If you experience out-of-memory errors:

Reduce BROWSER_MAX_PAGES_NUMBER
Use a smaller viewport (BROWSER_WIDTH, BROWSER_HEIGHT)
Run in headless mode (BROWSER_TYPE=chromium-headless)
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

Storage Configuration

Store recordings and artifacts in S3 or Azure Blob

​Browser modes

​Headful (default)

​Headless

​Use Your Own Chrome

​CDP Connect (External Chrome)

​Setting up Use Your Own Chrome

​Step 1: Find your Chrome path

​Step 2: Configure Skyvern

​Setting up CDP Connect

​Step 1: Enable Chrome remote debugging

​Docker-reachable isolated profile fallback

​Windows Docker Desktop with chrome://inspect

​Step 2: Configure Skyvern

​Step 3: Verify connection

​Display settings

​Locale and timezone

​Viewport size

​Timeout settings

​When to adjust timeouts

​Advanced settings

​Browser logging

​Maximum pages

​Chrome policies

​Video recording path

​Memory considerations

​Scaling browsers

​Option 1: Vertical scaling

​Option 2: Horizontal scaling

​Option 3: External browser pool

​Next steps

Storage Configuration

Browser modes

Headful (default)

Headless

Use Your Own Chrome

CDP Connect (External Chrome)

Setting up Use Your Own Chrome

Step 1: Find your Chrome path

Step 2: Configure Skyvern

Setting up CDP Connect

Step 1: Enable Chrome remote debugging

Docker-reachable isolated profile fallback

Windows Docker Desktop with `chrome://inspect`

Step 2: Configure Skyvern

Step 3: Verify connection

Display settings

Locale and timezone

Viewport size

Timeout settings

When to adjust timeouts

Advanced settings

Browser logging

Maximum pages

Chrome policies

Video recording path

Memory considerations

Scaling browsers

Option 1: Vertical scaling

Option 2: Horizontal scaling

Option 3: External browser pool

Next steps