rayobrowse: Instructions file for Codex

AGENTS.md

Setup, verification, and usage notes for AI agents and automated pipelines working with the public rayobrowse repository.

What This Project Is

rayobrowse is a Chromium-based stealth browser that runs inside Docker. It exposes an HTTP daemon on port 9222. Your automation code calls GET /connect, receives a CDP WebSocket URL as plain text, and passes that URL to Playwright, Puppeteer, Selenium, or any other CDP client.

The local and cloud usage model is intentionally the same. For local work, use http://localhost:9222. For rayobrowse Cloud, use https://cloud.rayobrowse.com with an API key.

Prerequisites

• Docker with Compose v2 (docker compose)
• Python 3.10+ for Python examples
• Node.js 18+ for Node examples
• About 2 GB free RAM for a basic local run

Local Setup

cp .env.example .env
docker compose up -d
curl http://localhost:9222/health

By using rayobrowse, you agree to the licenses in LICENSE and BROWSER_BINARY_LICENSE.md.

Primary Usage Pattern

Do not connect Playwright or Puppeteer directly to /connect. /connect is an HTTP endpoint, not a CDP WebSocket endpoint.

Correct flow:

1. Call GET http://localhost:9222/connect.
2. Read the CDP WebSocket URL from the response body.
3. Connect your CDP client to that returned URL.
4. Let the browser close when the CDP session closes, unless the task requires explicit lifecycle control.

Python example:

import httpx
from playwright.sync_api import sync_playwright

resp = httpx.get(
    "http://localhost:9222/connect",
    params={"os": "windows", "headless": "false", "vnc": "true"},
    timeout=120,
)
resp.raise_for_status()

cdp_url = resp.text.strip()
vnc_url = resp.headers.get("x-vnc-url") or "http://localhost:6080/vnc.html"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp_url)
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com")
    print(page.title())
    print(f"To view your browser in VNC go to: {vnc_url}")
    browser.close()