Getting Started

Quickstart

Go from zero to cloud browser automation in under 2 minutes. BrowseFleet is self-hosted; you run the server, the SDK talks to it.

1. Run the server

One Docker container. Chromium is baked in.

docker run -p 3000:3000 --shm-size=2g ghcr.io/therjmurray/browsefleet:latest

The default is authless and binds to 0.0.0.0:3000. Fine for localhost; never expose this directly to the internet. Set API_KEYS in your .env and put a reverse proxy in front before going public. See the self-host guide.

2. Install the SDK

Install the BrowseFleet client library for your language, or use curl directly.

npm install browsefleet puppeteer-core

3. Create a session

Launch a cloud browser and get a CDP WebSocket URL to connect your automation tools.

curl -X POST http://localhost:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{
    "stealth": "full",
    "viewport": { "width": 1920, "height": 1080 }
  }'

# Response:
# {
#   "id": "sess_abc123",
#   "status": "active",
#   "websocketUrl": "ws://localhost:3000/cdp/sess_abc123",
#   "viewerUrl": "http://localhost:3000/v1/sessions/sess_abc123/live",
#   "createdAt": "2026-04-02T12:00:00.000Z",
#   "expiresAt": "2026-04-02T12:30:00.000Z",
#   "timeout": 1800000,
#   "stealth": "full",
#   "viewport": { "width": 1920, "height": 1080 }
# }

4. Connect Puppeteer

Use the CDP WebSocket URL to connect Puppeteer, Playwright, or any CDP-compatible tool.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: session.websocketUrl,
});

const page = await browser.newPage();
await page.goto('https://example.com');
const title = await page.title();
console.log(title); // "Example Domain"

await browser.disconnect();
await bf.sessions.release(session.id);

5. Scrape a page

Or skip sessions entirely and use the quick scrape endpoint for one-off tasks.

curl -X POST http://localhost:3000/v1/scrape \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{ "url": "https://example.com" }'

# Returns: { url, statusCode, title, html, cleanedHtml, markdown, readability, links, metadata }

6. Take a screenshot

Capture a full-page screenshot with a single call.

curl -X POST http://localhost:3000/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{ "url": "https://example.com", "fullPage": true }' \
  --output screenshot.png

Next steps

Explore the full API reference for sessions, computer API, agents, and more.

Sessions APIComputer API