Node.js SDK Reference

Rayobrowse class

import { Rayobrowse } from 'rayobrowse';

const client = new Rayobrowse({
  endpoint: 'wss://cloud.rayobrowse.com', // or 'ws://localhost:9222'
  apiKey: 'your-api-key',                 // required for cloud
});

Constructor

Property	Type	Description
endpoint	string	WebSocket endpoint (local or cloud)
apiKey	string	API key (required for cloud, can be empty string for local)

connectUrl(options?): Promise<string>

Create a browser session and return the CDP WebSocket URL.

Option	Type	Description
backend	string	Engine identifier
os	string	Target OS fingerprint
proxy	string	Proxy URL
headless	boolean	Run headless
maxLifetime	number	Session TTL in seconds
vnc	boolean	Start noVNC session
browserLanguage	string	Accept-Language header
uiLanguage	string	UI locale
browserVersionMin	number	Minimum browser version
browserVersionMax	number	Maximum browser version
screenWidthMin	number	Minimum screen width
screenHeightMin	number	Minimum screen height
forceVisibility	boolean	Force browser visibility
metadata	object	Custom metadata (JSON-stringified)
protection	Record<string, string>	Per-feature protection overrides

reconnectUrl(sessionId): Promise<string>

Reconnect to an existing session by ID.

close(sessionId?): Promise<void>

Close a session. Defaults to the most recent session. Throws RayobrowseError if no session ID is available.

listBrowsers(): Promise<Record<string, unknown>[]>

List active browser sessions.

getHealth(): Promise<HealthStatus>

Check service health.

getSessionCount(): Promise<{ limit: number; remaining: number }>

Check concurrent session limit and remaining capacity.

Properties

Property	Type	Description
sessionId	string | null	Session ID from the most recent connectUrl() call
vncUrl	string | null	VNC URL when vnc: true was used

Types

ConnectOptions

interface ConnectOptions {
  backend?: string;
  os?: string;
  proxy?: string;
  headless?: boolean;
  maxLifetime?: number;
  vnc?: boolean;
  browserLanguage?: string;
  uiLanguage?: string;
  browserVersionMin?: number;
  browserVersionMax?: number;
  screenWidthMin?: number;
  screenHeightMin?: number;
  forceVisibility?: boolean;
  metadata?: Record<string, unknown>;
  protection?: Record<string, string>;
}

HealthStatus

interface HealthStatus {
  status: string;
  uptime: number;
}

Error classes

Error	Status	Properties	Description
RayobrowseError	any	statusCode, body	Base error class
AuthError	401		Invalid or missing API key
ConcurrencyLimitError	429	limit, active, retryAfter	Concurrent browser limit reached
RateLimitError	429	retryAfter	Request rate limit exceeded
BrowserCreateError	varies	statusCode, body	Browser creation failed