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

``bash
npx breamer
`

Or with options:

`bash
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:

`bash


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:

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

API Endpoints

$3

Service info.

$3

Health check with browser connection status and metrics:

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

$3

Get the WebSocket endpoint for browser connection.

Connecting from a Client

`ts
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

`ts
import { startServer } from "breamer";

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

License

ISC