Python SDK Reference

`Rayobrowse` class

from rayobrowse import Rayobrowse

client = Rayobrowse(
    endpoint="ws://localhost:9222",  # or "wss://cloud.rayobrowse.com"
    api_key=None,                    # required for cloud, optional for local
    timeout=120.0,                   # HTTP request timeout in seconds
)

Constructor parameters

Parameter	Type	Default	Description
`endpoint`	`str`	`"ws://localhost:9222"`	WebSocket endpoint (local or cloud)
`api_key`	`str \| None`	`None`	API key for cloud or paid local tier
`timeout`	`float`	`120.0`	HTTP request timeout in seconds

`connect_url(**kwargs) -> str`

Get a CDP WebSocket URL for a new browser session. Pass the returned URL to playwright.chromium.connect_over_cdp().

Parameter	Type	Default	Description
`backend`	`str`	`DEFAULT_ENGINE`	Engine identifier
`os`	`str`	`"windows"`	Target OS fingerprint: `windows`, `linux`, `android`, `macos`
`proxy`	`str \| None`	`None`	Proxy URL (`http://user:pass@host:port`)
`headless`	`bool`	`False`	Run headless
`protection`	`ProtectionConfig \| dict \| None`	`None`	Per-feature fingerprint overrides
`browser_language`	`str \| None`	`None`	Accept-Language header value
`max_lifetime`	`int \| None`	`None`	Session TTL in seconds
`vnc`	`bool`	`False`	Start per-browser noVNC session
`**kwargs`			Additional query parameters passed through

Local mode: Returns a ws://... URL directly (no HTTP call made). Cloud mode: Makes GET /connect to the gateway, returns the direct CDP URL.

`reconnect_url(session_id: str) -> str`

Get the CDP URL for an existing session. Useful when a client disconnects and wants to reconnect without creating a new browser.

`close() -> None`

Close the browser from the most recent connect_url() call. If no session is active, this is a no-op.

`list_browsers() -> list[dict]`

List active browser sessions.

`get_health() -> dict`

Check service health. Returns the JSON response from GET /health.

Properties

Property	Type	Description
`last_session_id`	`str \| None`	Session ID from the most recent `connect_url()` call (cloud only)
`last_vnc_url`	`str \| None`	VNC URL from the most recent `connect_url(vnc=True)` call

Exceptions

Exception	When raised
`RayobrowseError`	Base exception for all SDK errors
`BrowserCreateError`	Browser creation failed (includes `status_code` and `body`)
`ConnectionFailedError`	Cannot reach the rayobrowse service
`DaemonNotRunning`	Local daemon is not running
`LicenseLimitExceeded`	Concurrent browser limit exceeded
`TermsNotAccepted`	Terms of service not accepted
`ConcurrencyLimitError`	Cloud concurrency limit reached (includes `limit`, `active`, `retry_after`)
`RateLimitError`	Request rate limit exceeded (includes `retry_after`)

Python SDK Reference

Rayobrowse class

Constructor parameters

connect_url(**kwargs) -> str

reconnect_url(session_id: str) -> str

close() -> None

list_browsers() -> list[dict]

get_health() -> dict