Local Mode Overview

In local mode, rayobrowse runs as a Docker container on your own machine or server. Your automation code connects to the daemon over CDP (Chrome DevTools Protocol) on localhost:9222.

Architecture

┌─────────────────────────────────────────────┐
│  Your host machine                          │
│                                             │
│  ┌───────────────────┐                      │
│  │  Your code        │                      │
│  │  (Playwright,     │                      │
│  │   Puppeteer, etc) │                      │
│  └────────┬──────────┘                      │
│           │ CDP WebSocket                   │
│           ▼                                 │
│  ┌───────────────────────────────────────┐  │
│  │  rayobrowse container (:9222)         │  │
│  │                                       │  │
│  │  ┌─────────┐  ┌──────────────────┐    │  │
│  │  │ Daemon  │  │ Fingerprint DB   │    │  │
│  │  │ server  │  │ (thousands of    │    │  │
│  │  │         │  │  real profiles)  │    │  │
│  │  └────┬────┘  └──────────────────┘    │  │
│  │       │                               │  │
│  │       ▼                               │  │
│  │  ┌──────────────────┐                 │  │
│  │  │ Chromium (custom  │                │  │
│  │  │ patched binary)   │                │  │
│  │  └──────────────────┘                 │  │
│  │                                       │  │
│  │  noVNC viewer (:6080)                 │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Components

Component	Where it lives	What it does
Daemon server	Inside Docker container	Manages browser lifecycle, exposes /connect and REST API
Chromium binary	Inside Docker container	Custom-patched Chromium with anti-detection modifications
Fingerprint engine	Inside Docker container	Assigns real-world device profiles to each session
Python/Node SDK	Installed via pip/npm on host	Optional lightweight client that talks to the daemon
noVNC	Inside Docker container	Browser for watching sessions live on port 6080

Note

Zero system dependencies on your host machine beyond Docker. No Xvfb, no font packages, no Chromium install needed.

Two ways to create browsers

Method	How it works	Best for
/connect endpoint (recommended)	Connect to ws://localhost:9222/connect?... — browser auto-created on connect, cleaned up on disconnect. No SDK needed.	Quick scripts, any CDP client (Playwright, Puppeteer, Selenium), third-party tools (OpenClaw, Scrapy)
SDK create_browser()	Install the SDK, call the function, get a CDP WebSocket URL back	Fine-grained control, multiple browsers, custom lifecycle management

Tip

Start with the /connect endpoint — it works with any language and any CDP client with zero extra dependencies. You can always switch to the SDK later if you need advanced features.

Requirements

• Docker — the browser runs inside a container
• Any CDP client (Playwright, Puppeteer, Selenium, etc.) — for automation
• 2GB+ RAM available (~300MB per browser instance)

Works on Linux, Windows (native or WSL2), and macOS. Both x86_64 and ARM64 (Apple Silicon, AWS Graviton) are supported.