Remote Mode

By default, rayobrowse runs in local mode — your code connects to the daemon on localhost. For cloud deployments where external clients need direct CDP access, switch to remote mode.

How it works

┌──────────────┐      POST /browser       ┌─────────────────────────┐
│  Your Server  │ ──────────────────────► │  rayobrowse             │
│  (controller) │ ◄────── ws_endpoint ─── │  (remote mode, :80)     │
└──────────────┘                          └─────────────────────────┘
                                                    ▲
┌──────────────┐      CDP WebSocket                 │
│  End User /   │ ──────────────────────────────────┘
│  Worker       │   (direct connection, no middleman)
└──────────────┘

Your server requests a browser via the REST API (authenticated with your API key). The daemon returns a ws_endpoint URL. The client connects directly to the browser over CDP.

Setup

Configure .env

STEALTH_BROWSER_ACCEPT_TERMS=true
STEALTH_BROWSER_API_KEY=your_api_key_here
STEALTH_BROWSER_DAEMON_MODE=remote
RAYOBROWSE_PORT=80
# Optional: set if you have a domain
# STEALTH_BROWSER_PUBLIC_URL=http://browser.example.com

Start
Terminal window
```
docker compose up -d
```

Connect

Option A: /connect with api_key in the URL (simplest)

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        "ws://your-server/connect?headless=true&os=windows&api_key=your_api_key_here"
    )
    page = browser.new_context().new_page()
    page.goto("https://example.com")

Option B: REST API (for managing multiple browsers)

curl -X POST http://your-server/browser \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"headless": true, "os": "windows"}'

Response:

{
  "success": true,
  "data": {
    "browser_id": "br_59245e8658532863",
    "ws_endpoint": "ws://your-server/cdp/br_59245e8658532863"
  }
}

Authentication (remote mode)

In remote mode, management endpoints require your API key:

Endpoint	Auth Required	How to authenticate
`WS /connect`	Yes	`api_key` query parameter
`POST /browser`	Yes	`X-API-Key` or `Authorization: Bearer` header
`GET /browsers`	Yes	Same
`DELETE /browser/{id}`	Yes	Same
`GET /health`	No	—
`WS /cdp/{browser_id}`	No	Browser ID acts as the token

Public IP auto-detection

When STEALTH_BROWSER_PUBLIC_URL is not set, the daemon automatically detects the server’s public IP at startup. This works well for auto-scaling cloud servers — each instance discovers its own IP without DNS configuration.

TLS / HTTPS

The daemon serves HTTP. For HTTPS, put a reverse proxy in front (Cloudflare, nginx, Caddy). If using Cloudflare, point your domain at the server IP and enable the proxy — no server-side TLS configuration needed.