breamer

breamer

Always-on CDP (Chrome DevTools Protocol) server via WSS for remote browser automation.

Run a persistent Chrome browser on any machine, expose it via Cloudflare Tunnel, and connect from anywhere using Puppeteer.

Quick Start

npx breamer

Or with options:

npx breamer --port 3000 --browser browser.yourdomain.com

CLI Options

Option	Env Variable	Default	Description
-p, --port	PORT	3000	HTTP server port
-c, --chrome-port	CHROME_DEBUG_PORT	9222	Chrome remote debugging port
-t, --tunnel	TUNNEL_HOSTNAME	-	Cloudflare Tunnel hostname for HTTP API
-b, --browser	BROWSER_HOSTNAME	-	Cloudflare Tunnel hostname for Chrome WebSocket
--headless	HEADLESS=true	false	Run Chrome in headless mode
--heap-size	CHROME_HEAP_SIZE_MB	512	Chrome V8 heap size limit in MB

Cloudflare Tunnel Setup

Expose both the HTTP server and Chrome's debug port:

# Terminal 1: HTTP API
cloudflared tunnel --url http://localhost:3000

# Terminal 2: Chrome WebSocket
cloudflared tunnel --url http://localhost:9222

Pass both hostnames to breamer:

npx breamer --tunnel api.yourdomain.com --browser browser.yourdomain.com

API Endpoints

GET /

Service info.

GET /health

Health check with browser connection status and metrics:

• Uptime
• Pages created/navigated/closed
• Console and page errors

GET /cdp

Get the WebSocket endpoint for browser connection.

Connecting from a Client

import puppeteer from "puppeteer";

// Fetch the CDP endpoint
const res = await fetch("https://api.yourdomain.com/cdp");
const { wsEndpoint } = await res.json();

// Connect to the remote browser
const browser = await puppeteer.connect({
  browserWSEndpoint: wsEndpoint,
  defaultViewport: null,
});

// Use it!
const page = await browser.newPage();
await page.goto("https://example.com");

Programmatic Usage

import { startServer } from "breamer";

await startServer({
  port: 3000,
  chromeDebugPort: 9222,
  browserHostname: "browser.yourdomain.com",
  tunnelHostname: "api.yourdomain.com",
  headless: false,
});

License

ISC