263 lines
6.5 KiB
Plaintext
263 lines
6.5 KiB
Plaintext
---
|
|
title: Browser Configuration
|
|
subtitle: Configure browser modes, display settings, and external Chrome connections
|
|
slug: self-hosted/browser
|
|
---
|
|
|
|
Skyvern uses Playwright with Chromium to execute browser automations.
|
|
|
|
## Browser modes
|
|
|
|
The `BROWSER_TYPE` setting controls how Skyvern runs the browser.
|
|
|
|
### Headful (default)
|
|
|
|
```bash .env
|
|
BROWSER_TYPE=chromium-headful
|
|
```
|
|
|
|
The browser runs with a visible window. In Docker, this displays on a virtual framebuffer (Xvfb).
|
|
|
|
### Headless
|
|
|
|
```bash .env
|
|
BROWSER_TYPE=chromium-headless
|
|
```
|
|
|
|
The browser runs without any display.
|
|
|
|
<Note>
|
|
Some websites detect and block headless browsers. If you encounter issues with bot detection, try headful mode with a virtual display.
|
|
</Note>
|
|
|
|
### CDP Connect (External Chrome)
|
|
|
|
```bash .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
|
|
|
|
<CodeGroup>
|
|
```bash macOS
|
|
/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
|
|
```
|
|
|
|
```powershell Windows
|
|
"C:\Program Files\Google\Chrome\Application\chrome.exe" `
|
|
--remote-debugging-port=9222 `
|
|
--user-data-dir="C:\chrome-cdp-profile" `
|
|
--no-first-run `
|
|
--no-default-browser-check
|
|
```
|
|
|
|
```bash Linux
|
|
google-chrome \
|
|
--remote-debugging-port=9222 \
|
|
--user-data-dir="$HOME/chrome-cdp-profile" \
|
|
--no-first-run \
|
|
--no-default-browser-check
|
|
```
|
|
</CodeGroup>
|
|
|
|
The `--user-data-dir` flag creates a separate profile for Skyvern, preserving your main Chrome profile.
|
|
|
|
### Step 2: Configure Skyvern
|
|
|
|
```bash .env
|
|
BROWSER_TYPE=cdp-connect
|
|
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
|
|
```
|
|
|
|
When running Skyvern in Docker:
|
|
|
|
| Host OS | URL |
|
|
|---------|-----|
|
|
| macOS/Windows | `http://host.docker.internal:9222/` |
|
|
| Linux | `http://172.17.0.1:9222/` |
|
|
|
|
### Step 3: Verify connection
|
|
|
|
Test that Skyvern can reach Chrome:
|
|
|
|
```bash
|
|
curl http://localhost:9222/json/version
|
|
```
|
|
|
|
You should see Chrome's version information.
|
|
|
|
<Warning>
|
|
CDP mode exposes Chrome to network access. Only use this in trusted environments and bind to localhost when possible.
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## Display settings
|
|
|
|
Configure how the browser appears to websites. These settings affect geolocation detection and content rendering.
|
|
|
|
### Locale and timezone
|
|
|
|
```bash .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
|
|
|
|
```bash .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.
|
|
|
|
```bash .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
|
|
|
|
```bash .env
|
|
BROWSER_LOGS_ENABLED=true
|
|
```
|
|
|
|
When enabled, browser console logs are captured in artifacts. Useful for debugging JavaScript errors on target sites.
|
|
|
|
### Maximum pages
|
|
|
|
```bash .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
|
|
|
|
```bash .env
|
|
BROWSER_POLICY_FILE=/etc/chromium/policies/managed/policies.json
|
|
```
|
|
|
|
Path to a Chrome policy file for enterprise configurations.
|
|
|
|
### Video recording path
|
|
|
|
```bash .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:
|
|
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](/self-hosted/kubernetes) for orchestrated scaling.
|
|
|
|
### Option 3: External browser pool
|
|
|
|
Use a browser pool service like Browserless or your own Playwright grid, then connect via CDP:
|
|
|
|
```bash .env
|
|
BROWSER_TYPE=cdp-connect
|
|
BROWSER_REMOTE_DEBUGGING_URL=http://browserless:3000/
|
|
```
|
|
|
|
---
|
|
|
|
## Next steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Proxy Setup" icon="shield" href="/self-hosted/proxy">
|
|
Configure proxies to avoid bot detection
|
|
</Card>
|
|
<Card title="Storage Configuration" icon="hard-drive" href="/self-hosted/storage">
|
|
Store recordings and artifacts in S3 or Azure Blob
|
|
</Card>
|
|
</CardGroup>
|