Migrate from V1

This guide covers everything you need to update when migrating an Enterprise deployment from a V1 image to a V2 image. For self-hosted Docker migrations, see also the BaaS Docker migration reference.

Connection URL Paths

V2 requires the browser type in the URL path. Requests to V1-style paths on a V2 image return 404 Not Found.

Use case	V1	V2
Playwright	wss://chrome.browserless.io/playwright	wss://chrome.browserless.io/chrome/playwright
Puppeteer (Chrome)	wss://chrome.browserless.io	wss://chrome.browserless.io/chrome
Puppeteer (Chromium)	wss://chrome.browserless.io	wss://chrome.browserless.io/chromium

Launch Arguments Format

V2 consolidates all launch flags into a single JSON launch query parameter instead of individual query parameters. The value must be URL-encoded. See Encoding the launch value for details.

V1

?token=YOUR_API_TOKEN_HERE&--use-gl=angle&--use-angle=gl

V2 (URL-encoded)

?token=YOUR_API_TOKEN_HERE&launch=%7B%22args%22%3A%5B%22--use-gl%3Dangle%22%2C%22--use-angle%3Dgl%22%5D%7D

Other launch flag examples:

Window size

# V1
ws://localhost:3000?token=ABCD&--window-size=1920,1080

# V2
ws://localhost:3000?token=ABCD&launch={"args":["--window-size=1920,1080"]}

Headless mode

# V1
ws://localhost:3000?token=ABCD&headless=shell

# V2
ws://localhost:3000?token=ABCD&launch={"headless":"shell"}

Unknown query parameters or JSON POST parameters now return a 4xx error instead of being silently ignored.

User Data Directory

V2 with Playwright does not support --user-data-dir as a launch argument. Puppeteer on V2 still supports it.

Available Browsers

V2 adds Firefox and WebKit alongside Chrome and Chromium:

• /chrome/playwright
• /chromium/playwright
• /firefox/playwright
• /webkit/playwright

Docker Environment Variables

Multiple environment variables have changed in V2 for simplicity and clarity. Browserless logs deprecated variable names on startup, so check your logs during migration.

Removed Variables (No Replacements)

These variables have been removed. Use the equivalent per-request option in your API or library connect calls instead:

Removed variable	Alternative
CHROME_REFRESH_TIME	Pre-booted Chrome is no longer supported
DEFAULT_BLOCK_ADS	Use blockAds in API or library connect calls
DEFAULT_DUMPIO	Use dumpio in launch arguments
DEFAULT_HEADLESS	Use headless: false in launch arguments
DEFAULT_IGNORE_DEFAULT_ARGS	Use ignoreDefaultArgs in launch arguments
DEFAULT_IGNORE_HTTPS_ERRORS	Use acceptInsecureCerts in connect calls
DEFAULT_LAUNCH_ARGS	Use the args option in launch arguments
DEFAULT_STEALTH	Use the stealth option in connect calls
DISABLED_FEATURES	Fully deprecated
ENABLE_HEAP_DUMP	No longer supported
FUNCTION_BUILT_INS	No longer supported (new function implementation)
FUNCTION_ENABLE_INCOGNITO_MODE	No longer supported
FUNCTION_ENV_VARS	No longer supported
FUNCTION_EXTERNALS	No longer supported (new function implementation)
KEEP_ALIVE	Pre-booting and keep-alive are no longer supported
PREBOOT_CHROME	Pre-booting and keep-alive are no longer supported
PRINT_GET_STARTED_LINKS	Ignored
WORKSPACE_DELETE_EXPIRED	No longer needed (libraries handle this now)
WORKSPACE_DIR	No longer needed (libraries handle this now)
WORKSPACE_EXPIRE_DAYS	No longer needed (libraries handle this now)

Renamed Variables

Browserless will log these and handle them internally, but you should update them to prevent deprecation warnings:

V1	V2
CONNECTION_TIMEOUT	TIMEOUT
DEFAULT_USER_DATA_DIR	DATA_DIR
ENABLE_API_GET	ALLOW_GET
ENABLE_CORS	CORS
MAX_CONCURRENT_SESSIONS	CONCURRENT
PRE_REQUEST_HEALTH_CHECK	HEALTH
PROXY_URL	EXTERNAL
QUEUE_LENGTH	QUEUED
TOKEN	Remains TOKEN, but is randomly generated when none is set

Docker Registry Change

Docker images have moved from Docker Hub to GitHub's container registry. Use ghcr.io/browserless or visit the Packages page.

Other Breaking Changes

• Selenium and WebDriver: No longer supported in V2.
• /function API: Now runs inside the browser's JavaScript runtime instead of Node.js. Uses ECMAScript modules (export default) instead of CommonJS (module.exports). Test all /function calls thoroughly before deploying.
• blockAds: Now uses uBlock Origin instead of request interception.
• /stats API: Moved to /performance.
• /screencast API: Removed in favor of a library-based embedded API approach.
• waitFor parameter: Removed from /pdf, /screenshot, and /scrape APIs. Use Puppeteer's waitForEvent, waitForFunction, waitForSelector, or waitForTimeout instead.
• TOKEN enforcement: A random token is generated when none is provided, so a token is always required.

Upgrade Process

Coordinate upgrades with Browserless support:

1. Request a test environment — Browserless provides a separate API key pointing to a worker running the newer image (same machine profile as production).
2. Run your integration tests — Verify connection URLs, launch parameters, and that screenshots and PDFs render correctly.
3. Coordinate production upgrade — The production fleet is updated via a Relaunch onto new workers. IP addresses will change, so update any firewall allowlists afterward.