Managed Browsers

The platform runs a pool of real browsers for you. Your code connects to one over a WebSocket and drives it with Playwright — you never launch or install a browser yourself, and you never manage proxy credentials. Every browser always egresses through a proxy; the host IP is never exposed.

For each granted engine the platform injects a ready-to-use WebSocket URL into your job’s environment, with the access token already embedded:

BROWSER_WS_URL_PLAYWRIGHT
BROWSER_WS_URL_NODRIVER
BROWSER_WS_URL_CAMOUFOX

Read the URL from the environment and connect — that’s the whole setup.

You never set a proxy in the browser, and you never pass credentials. You only state your intent with the proxy and country query parameters (below); the service owns the rest.

Browser engines

Engine	Driver call	What it is	Reach for it when
playwright	`chromium.connect()`	Managed Chromium over the Playwright protocol.	Default choice — fast, full Playwright API, JS rendering.
nodriver	`chromium.connect_over_cdp()`	Stealth Chrome (real display via Xvfb, software GL) driven over CDP.	Targets with bot detection that flag headless Chromium.
camoufox	`firefox.connect()`	Anti-fingerprint Firefox build with a spoofed device profile.	Aggressive fingerprinting defenses where Chromium gets caught.

Connecting to a browser

The only thing that changes between engines is which environment variable you read and which driver call you use.

playwright — Chromium

Use connect() with the Chromium driver:


from playwright.sync_api import sync_playwright
import os
 
# The platform injects a ready-to-use WebSocket URL (token already embedded)
# into your job's environment. Read it — never hard-code a URL or a token.
ws = os.environ["BROWSER_WS_URL_PLAYWRIGHT"]
 
with sync_playwright() as p:
    browser = p.chromium.connect(ws)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

nodriver — Stealth Chrome

Stealth Chrome is driven over CDP — use connect_over_cdp(), not connect():


from playwright.sync_api import sync_playwright
import os
 
ws = os.environ["BROWSER_WS_URL_NODRIVER"]
 
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(ws)
    page = browser.new_page()
    page.goto("https://example.com")
    browser.close()

camoufox — Firefox

Camoufox is a Firefox build — connect with the firefox driver:


from playwright.sync_api import sync_playwright
import os
 
ws = os.environ["BROWSER_WS_URL_CAMOUFOX"]
 
with sync_playwright() as p:
    browser = p.firefox.connect(ws)
    page = browser.new_page()
    page.goto("https://example.com")
    browser.close()

Choosing the proxy

You select the egress proxy with two optional query parameters on the WebSocket URL. The service owns the credentials — you only state your intent:

Parameter	Values	Default
`proxy`	`datacenter`, `residential`	`datacenter`
`country`	2-letter code, e.g. `us`, `mx`, `br`	provider default

A small helper keeps it tidy. The injected URL already contains the token, so always append with &:


import os
 
def browser_url(engine: str, *, proxy: str = "datacenter", country: str | None = None) -> str:
    """Append the egress selection to the platform-injected WS URL.
 
    engine  : "playwright" | "nodriver" | "camoufox"
    proxy   : "datacenter" (default) or "residential"
    country : optional 2-letter code, e.g. "us", "mx", "br"
    """
    base = os.environ[f"BROWSER_WS_URL_{engine.upper()}"]
    url = f"{base}&proxy={proxy}"
    if country:
        url += f"&country={country}"
    return url
 
# Residential egress from Mexico:
ws = browser_url("nodriver", proxy="residential", country="mx")

If you send nothing, you get a datacenter proxy. The choice is per connection, so two browsers in the same job can use different tiers or countries.

Full example


from playwright.sync_api import sync_playwright
import os
 
def browser_url(engine, *, proxy="datacenter", country=None):
    base = os.environ[f"BROWSER_WS_URL_{engine.upper()}"]
    url = f"{base}&proxy={proxy}"
    if country:
        url += f"&country={country}"
    return url
 
with sync_playwright() as p:
    # Stealth Chrome, residential IP in the US — chosen entirely by the URL.
    browser = p.chromium.connect_over_cdp(
        browser_url("nodriver", proxy="residential", country="us")
    )
    page = browser.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))  # the egress IP — a proxy IP, never the host's
    browser.close()

Rules

🚫

Never send proxy credentials. Do not set a proxy in the browser launch/context options, and do not send any X-Insight-Proxy-* header — the service rejects credential headers with 400. Pick a tier with ?proxy= instead.

Always proxied. Every browser egresses through a proxy — the host IP is never exposed, even for background requests.
Metered separately. Browser proxy traffic shows up in Analytics as browser_datacenter / browser_residential, distinct from raw proxy usage.
On-demand. Browsers start when you connect. The first connection waits a few seconds for cold start; close the browser when you’re done so the slot frees immediately.