Quickstart (Local)

Get rayobrowse running locally in under 5 minutes. All you need is Docker and any CDP client (Playwright, Puppeteer, Selenium, etc.) — no SDK required.

1. Set up environment

   git clone https://github.com/rayobyte-data/rayobrowse.git
   cd rayobrowse
   cp .env.example .env

   Open .env and set STEALTH_BROWSER_ACCEPT_TERMS=true to accept the license.

2. Start the container

   docker compose up -d

   Docker automatically pulls the correct image for your architecture (x86_64 or ARM64).

3. Verify it’s running

   curl http://localhost:9222/health
   # Should return: {"success": true, "data": {"status": "healthy", ...}}

4. Connect and automate

   Point any CDP client at the /connect endpoint — rayobrowse creates a fresh browser on connection and cleans it up when you disconnect.

   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=false&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=false&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=false&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();
   })();

   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=false&os=windows",
       options=options,
   )
   driver.get("https://example.com")
   print(driver.title)
   driver.quit()

View the browser live at http://localhost:6080/vnc.html (noVNC).

Tip

rayobrowse also provides Python and Node.js SDKs for advanced use cases like managing multiple browsers, custom lifecycle control, and session management. The SDKs are optional — the /connect endpoint is all you need to get started.

Next steps

• /connect parameters — customize fingerprints, proxy, headless mode
• Configuration — environment variables, ports, noVNC
• SDKs — optional Python and Node.js clients for programmatic control
• Integrations — Playwright, Puppeteer, Selenium, OpenClaw, Scrapy