Back to blog

Unblocking Browser Quick Start Guide

vytenis kaubre avatar

Vytenis Kaubrė

2025-10-22

3 min read

Unblocking Browser is a stealth-first and cloud-hosted headless browser infrastructure that handles anti-bots, CAPTCHAs, and proxy management for you. It's AI-ready, scales instantly, and gives you full control over remote Chrome and Firefox browsers, so you can focus on your goals instead of maintaining infrastructure.

Follow this guide for everything you need to get started quickly.

Set up Unblocking Browser

Create a dashboard account and navigate to Scraping SolutionsUnblocking BrowserPricing. Choose a plan that suits your needs and contact our sales team to continue. You may also get a free trial to test the product.

Create a product user

After receiving access, you’ll be prompted to create an Unblocking Browser user in the dashboard. Enter a username and password that will be used for authentication.

Test your first request

Use Playwright, Puppeteer, and other tools compatible with Chrome DevTools Protocol (CDP) to connect to Unblocking Browser. You may also integrate directly with AI applications via the Model Context Protocol (MCP), allowing you to automate every browsing process.

Playwright example in Python

Install the Playwright library through your terminal:

pip install playwright

Use your Unblocking Browser credentials and run the code:

from playwright.sync_api import sync_playwright

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

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto('https://oxylabs.io/')
    print(page.title())
    browser.close()

Playwright example in JavaScript

Install Playwright via your terminal:

npm init -y
npm install playwright

Enter your Unblocking Browser credentials and run the code:

const { chromium } = require('playwright');

(async () => {
    const username = 'your-username';
    const password = 'your-password';
    const endpoint = 'ubc.oxylabs.io';
    const browserUrl = `wss://${username}:${password}@${endpoint}`;

    const browser = await chromium.connectOverCDP(browserUrl);
    const page = await browser.newPage();
    await page.goto('https://oxylabs.io/');
    console.log(await page.title());
    await browser.close();
})();

Use with AI apps via MCP

You can give full control of Unblocking Browser to any AI application, such as Claude Desktop, Cursor, LangChain, and other AI-focused apps that support MCP. This allows you to automate complex web browsing tasks with human-like precision. Find more details in our documentation.

Here’s an example of an MCP configuration connecting Claude Desktop to Unblocking Browser:

{
    "mcpServers": {
        "oxylabs_unblocking_browser": {
            "command": "npx",
            "args": [
                "@playwright/mcp@latest",
                "--cdp-endpoint",
                "wss://username:password@ubc.oxylabs.io"
            ]
        }
    }
}

With this setup, Claude can easily navigate websites, bypass CAPTCHAs, and perform various browser actions like clicking, typing, and scrolling.

Browser types

At the moment, Unblocking Browser offers remote Chrome and Firefox browsers, each having unique strengths:

  • The Chrome browser is the fastest and most reliable, handles CAPTCHAs, emulates devices, and supports browser arguments.

  • The Firefox browser is the stealthiest with built-in anti-detection modifications and advanced fingerprint management.

Endpoints reference

Unblocking Browser uses the WebSocket protocol and has different connection endpoints for each browser:

  • Chrome: wss://ubc.oxylabs.io

  • Firefox: wss://ubs.oxylabs.io

If you’re located in the United States, connect via our US-based infrastructure for faster loading time and better browsing efficiency:

  • US-based Chrome: wss://ubc-us.oxylabs.io

  • US-based Firefox: wss://ubs-us.oxylabs.io

Check out our Chrome documentation and Firefox documentation to find more details and examples.

Additional functionalities

Built-in proxy servers

By default, the Chrome and Firefox environments use proxy servers to route requests through specific geographic locations. To specify your desired location, add the p_cc= parameter to the Unblocking Browser endpoint using a specific country's ISO-3166 code.

For example, to route Chrome web requests through a UK-based proxy pool, connect to:

wss://username:password@ubc.oxylabs.io?p_cc=UK

Device type (Chrome only)

You can specify the device type to emulate, making it easy to handle responsive layouts, mobile content, and device-specific behavior like CAPTCHAs or UI elements. Use the p_device= parameter with the supported values: desktop, mobile, or tablet.

For instance, to emulate mobile devices, your endpoint should look like this:

wss://username:password@ubc.oxylabs.io?p_device=mobile

CAPTCHA bypass (Chrome only)

The Chrome environment automatically detects and handles CAPTCHAs. You can track the event logs (start, end, and error) for debugging and specific use cases. Check out the documentation to learn more.

Additionally, you can manually trigger CAPTCHA detection and handling at any point during your session. This is useful in situations where CAPTCHAs appear after submitting forms or after specific user interactions.

Browser arguments (Chrome only)

For the Chrome-based Unblocking Browser, you can specify additional browser arguments using the bargs= parameter. This GET parameter defines the command-line arguments for browser startup. 

For example, to hide scrollbars, your connection endpoint should be: 

wss://username:password@ubc.oxylabs.io?bargs=hide-scrollbars

Refer to the table below for available browser arguments and see the documentation for more details.

Argument Description
force-color-profile:<profile> Force all monitors to be treated as though they have the specified color profile.
window-position:X,Y Specify the initial window position.
hide-scrollbars Prevent creating scrollbars for web content.
enable-features:<feature1>,<feature2>,<feature3> Comma-separated list of feature names to enable.
disable-notifications Disable the Web Notification and the Push APIs.

Session inspection

The Session Inspection Tool provides a graphical interface for debugging browser automation sessions. It's particularly useful when you need to visually observe page rendering, diagnose issues not visible in logs, or troubleshoot unexpected behavior in real-time.

Enable the tool by adding the o_vnc=true parameter to your connection endpoint:

wss://username:password@ubc.oxylabs.io?o_vnc=true

Visit our documentation to see an example of how to use the Session Inspection Tool.

Resources

If you have questions, feel free to contact our 24/7 support team. Take a look at Unblocking Browser’s documentation for more details, code samples, and guides:

Feel free to explore other developer resources for additional insights:

People also ask

When should I use a headless browser?

Use a headless browser when you need to fully render JavaScript-based content, handle dynamic web page elements, or simulate real user behavior. Headless browsers are essential for modern web scraping, automating repetitive browser tasks, testing web interfaces, and bypassing web blocks where simple HTTP requests aren't enough.

About the author

vytenis kaubre avatar

Vytenis Kaubrė

Technical Content Researcher

Vytenis Kaubrė is a Technical Content Researcher at Oxylabs. Creative writing and a growing interest in technology fuel his daily work, where he researches and crafts technical content, all the while honing his skills in Python. Off duty, you may catch him working on personal projects, learning all things cybersecurity, or relaxing with a book.

All information on Oxylabs Blog is provided on an "as is" basis and for informational purposes only. We make no representation and disclaim all liability with respect to your use of any information contained on Oxylabs Blog or any third-party websites that may be linked therein. Before engaging in scraping activities of any kind you should consult your legal advisors and carefully read the particular website's terms of service or receive a scraping license.

Related articles

Web Scraping with Gemini AI: Python Tutorial for Data Extraction
author avatar

Yelyzaveta Hayrapetyan

2025-10-17

Web Scraping PHP Tutorial with Scripts and Examples (2025)
author avatar

Augustas Pelakauskas

2025-10-16

How to Bypass CAPTCHA With Playwright
How to Bypass CAPTCHA With Playwright 2025
author avatar

Yelyzaveta Hayrapetyan

2025-10-14

Unblocking Browser

Automate web browsing and unlock data at scale from the toughest sites.

Get the latest news from data gathering world

Unblocking Browser

Automate web browsing and unlock data at scale from the toughest sites.