Quick Start: Headless Browser

Oxylabs Headless Browser is a cloud-hosted browser infrastructure that handles anti-bot systems, CAPTCHAs, and proxy rotation automatically. It is fully compatible with Playwright, Puppeteer, and the Model Context Protocol (MCP) for AI applications.

1

Setup & credentials

1. Create an account: Sign up at the Oxylabs Dashboard.

2. Choose a plan: Select a plan or a free trial under Scraping Solutions → Headless Browser.

3. Create user credentials: Head to the Users tab in the Headless Browser product section and create a username and password (These credentials are used for WebSocket authentication).

2

Your first request

Oxylabs Headless Browser uses the Chrome DevTools Protocol (CDP). You can connect to it using Playwright or Puppeteer without managing local browser binaries.

Python + Playwright example:

1. Install Playwright: pip install playwright

2. Run the following script (replace USERNAME and PASSWORD with your credentials):

from playwright.sync_api import sync_playwright

username = "USERNAME"
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}"

with sync_playwright() as p:
    # Connect to the remote Oxylabs browser
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    
    page.goto('https://oxylabs.io/')
    print(f"Page Title: {page.title()}")
    
    browser.close()

Connection reference

Use the endpoint that matches your preferred browser and geographic proximity:

Browser	Global endpoint	US-based endpoint
Chrome	wss://ubc.oxylabs.io	wss://ubc-us.oxylabs.io
Firefox	wss://ubs.oxylabs.io	wss://ubs-us.oxylabs.io

Customizing the browser

You can also pass instructions directly through the connection URL using query parameters:

Parameter	Example	Description
p_cc	?p_cc=US	Routes the browser's traffic through a specific country.
p_device	?p_device=mobile	Emulates a specific device type (Chrome only).
o_vnc	?o_vnc=true	Enables the Session Inspection Tool for visual debugging.

Next steps

• Want to monitor your browser? Learn about the Session Inspection Tool to visually track your script's interactions with the browser in real-time.

• Is your script too slow? Try Optimizing Traffic to block unnecessary assets from loading. This will increase scraping speed and reduce bandwidth consumption.

• Encountering errors or timeouts? Visit the Troubleshooting Guide to resolve common CDP connection issues, library version mismatches, and execution timeouts.

• Hitting a "403 Forbidden" on a major site? Check the Restricted Targets list to see which websites or services are restricted from access for the Headless Browser.