Connecting

Using /connect directly (recommended)

The simplest way to use rayobrowse cloud — pass your API key as a query parameter and connect any CDP client. No SDK required.

wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows

Python (Playwright)

from playwright.sync_api import sync_playwright

WS_URL = "wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(WS_URL)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

Node.js (Playwright)

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

const WS_URL = 'wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows';

(async () => {
  const browser = await chromium.connectOverCDP(WS_URL);
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
  await browser.close();
})();

Node.js (Puppeteer)

const puppeteer = require('puppeteer-core');

const WS_URL = 'wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows';

(async () => {
  const browser = await puppeteer.connect({ browserWSEndpoint: WS_URL });
  const page = (await browser.pages())[0] || await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
  await browser.disconnect();
})();

/connect parameters

Append any of these to the URL:

Parameter	Example	Description
token	token=YOUR_API_KEY	Required. Your API key
os	os=windows	Target fingerprint OS: windows, linux, android, macos
proxy	proxy=http://user:pass@host:port	Route traffic through a proxy
headless	headless=true	Run without GUI (default: true)
vnc	vnc=true	Start per-browser noVNC session
browser_language	browser_language=en-US	Accept-Language header
maxLifetime	maxLifetime=300	Session TTL in seconds
protection.*	protection.canvas=noise	Per-feature fingerprint overrides

With proxy

wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows&proxy=http://user:pass@host:port

With VNC

wss://cloud.rayobrowse.com/connect?token=YOUR_API_KEY&os=windows&vnc=true

The VNC URL is returned in the x-vnc-url response header.

Using the SDK (optional)

The SDK is a convenience wrapper that adds session management, reconnection, VNC URL retrieval, and typed errors. Install it only if you need those features.

Python

from rayobrowse import Rayobrowse
from playwright.sync_api import sync_playwright

client = Rayobrowse(
    endpoint="wss://cloud.rayobrowse.com",
    api_key="your-api-key",
)

ws_url = client.connect_url(
    os="windows",
    proxy="http://user:pass@host:port",
    headless=True,
)

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(ws_url)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

client.close()

Node.js

import { Rayobrowse } from 'rayobrowse';
import { chromium } from 'playwright';

const client = new Rayobrowse({
  endpoint: 'wss://cloud.rayobrowse.com',
  apiKey: 'your-api-key',
});

const wsUrl = await client.connectUrl({
  os: 'windows',
  proxy: 'http://user:pass@host:port',
  headless: true,
});

const browser = await chromium.connectOverCDP(wsUrl);
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

await client.close();

Tip

The SDK’s connect_url() / connectUrl() method calls the same /connect endpoint under the hood. It just wraps it in a nicer API with error handling and session tracking.

What happens under the hood

1. Your client connects to wss://cloud.rayobrowse.com/connect?token=...
2. The gateway creates a browser on one of the backend servers
3. The connection is upgraded to a direct CDP WebSocket to the browser
4. Response headers include x-session-id (for reconnection) and optionally x-vnc-url
5. Your CDP traffic goes directly to the browser — the gateway is not in the data path