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