/connect Endpoint

The /connect endpoint is the simplest way to use rayobrowse. Connect any CDP client to a single URL — a browser is auto-created on connection and cleaned up when you disconnect.

Basic usage

ws://localhost:9222/connect?headless=true&os=windows

No SDK needed. Any CDP-capable tool (Playwright, Puppeteer, Selenium, OpenClaw, Scrapy) can connect directly.

Python (Playwright)

# pip install playwright && playwright install
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        "ws://localhost:9222/connect?headless=true&os=windows"
    )
    page = browser.new_context().new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

Node.js (Playwright)

// npm install playwright
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.connectOverCDP(
    'ws://localhost:9222/connect?headless=true&os=windows'
  );
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
  await browser.close();
})();

Node.js (Puppeteer)

// npm install puppeteer-core
const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://localhost:9222/connect?headless=true&os=windows',
  });
  const page = (await browser.pages())[0] || await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
  await browser.disconnect();
})();

Python (Selenium)

# pip install selenium
from selenium import webdriver
from selenium.webdriver.chromium.options import ChromiumOptions

options = ChromiumOptions()
options.debugger_address = "localhost:9222"

driver = webdriver.Remote(
    command_executor="http://localhost:9222/connect?headless=true&os=windows",
    options=options,
)
driver.get("https://example.com")
print(driver.title)
driver.quit()

Parameters

Parameter	Default	Description
headless	true	true or false
os	linux	Fingerprint OS: windows, linux, android, macos
browser_name	chrome	Browser fingerprint type
browser_version_min	(latest)	Minimum Chrome version
browser_version_max	(latest)	Maximum Chrome version
proxy	(none)	Proxy URL, e.g. http://user:pass@host:port
browser_language	(auto)	Accept-Language value
ui_language	(auto)	Browser UI locale
screen_width_min	(auto)	Minimum screen width
screen_height_min	(auto)	Minimum screen height
api_key	(none)	Required in remote mode

Examples

Windows fingerprint with proxy

ws://localhost:9222/connect?headless=true&os=windows&proxy=http://user:pass@host:port

Headful mode (visible in noVNC)

ws://localhost:9222/connect?headless=false&os=windows

View at http://localhost:6080/vnc.html.

Specific Chrome version

ws://localhost:9222/connect?headless=true&os=windows&browser_version_min=146&browser_version_max=146

Tip

For optimal fingerprint matching, set browser_version_min and browser_version_max to 146 (the current Chromium version). Using a mismatched version may trigger detection on some sites.

Lifecycle

1. Created when a CDP client connects to the /connect WebSocket
2. Active while the WebSocket connection is alive
3. Cleaned up automatically after the connection closes (2-second grace period)

Each connection gets a fresh browser instance with a new fingerprint profile.