Quickstart (Cloud)

Connect to the managed rayobrowse cloud service — no Docker, no SDK required. Just an API key and any CDP client.

Prerequisites

• A rayobrowse cloud API key (contact support@rayobyte.com or fill out the access form)
• Python 3.10+ or Node.js 18+

Option A: Connect directly (no SDK)

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

1. Connect and automate

   The cloud WebSocket URL follows the same pattern as local mode, just with your API key:

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

   Python (Playwright)

   # pip install playwright && playwright install
   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)

   // npm install 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)

   // npm install puppeteer-core
   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();
   })();

   That’s it — no SDK installation, no client objects. Just a WebSocket URL.

2. Add a proxy or change fingerprint (optional)

   Append parameters to the URL just like local mode:

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

Option B: Use the SDK (optional)

The rayobrowse SDK adds convenience helpers for session management, VNC URLs, and lifecycle control. Install it only if you need those features.

1. Install the SDK

   Python

   pip install rayobrowse playwright && playwright install

   Node.js

   npm install rayobrowse playwright

2. Connect and automate

   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")
   
   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' });
   
   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();

3. View with VNC (optional)

   Pass vnc=True (Python) or vnc: true (Node) to connect_url() to get a live browser view:

   ws_url = client.connect_url(os="windows", vnc=True)
   print(f"Watch live: {client.last_vnc_url}")

How cloud mode differs from local

	Local	Cloud
Infrastructure	You run Docker on your own machine	Managed by rayobrowse
Scaling	Limited by your hardware	Scales automatically
Authentication	Optional (free tier, no key needed)	API key required
Connection	ws://localhost:9222/connect?...	wss://cloud.rayobrowse.com/connect?token=API_KEY&...
Pricing	Free (1 browser) or paid threads	Usage-based

Next steps

• Authentication — how API keys work
• Session management — close, reconnect, status
• Limits — concurrency and rate limiting
• SDK reference (Python) — full API
• SDK reference (Node.js) — full API