Automate a browser

BrowserBox runs a full browser (Chromium, Firefox, or WebKit) inside an isolated VM and exposes it via Playwright Server or Chrome DevTools Protocol. You connect with Playwright or Puppeteer from your host — no browser install needed on the host.

What you’ll build

A script that:

Launches a BrowserBox with Chromium
Connects via Playwright or Puppeteer
Navigates to a page and takes a screenshot
Scrapes content from the page

Prerequisites

Python (Playwright)
Node.js (Puppeteer)

pip install boxlite playwright

npm install @boxlite-ai/boxlite puppeteer-core

Use puppeteer-core (not puppeteer) since the browser runs inside the BrowserBox, not on your host.

Step 1: Launch a BrowserBox

Create a BrowserBox and get a connection endpoint.

Python (Playwright)
Node.js (Puppeteer)

browser.py

import asyncio
from boxlite import BrowserBox, BrowserBoxOptions

async def main():
    opts = BrowserBoxOptions(browser="chromium", memory=2048, cpu=2)
    async with BrowserBox(opts) as browser:
        ws = await browser.playwright_endpoint()
        print(f"Playwright endpoint: {ws}")
        # → ws://localhost:3000/


if __name__ == "__main__":
    asyncio.run(main())

browser.js

import { BrowserBox } from '@boxlite-ai/boxlite';

async function main() {
  const box = new BrowserBox({ browser: 'chromium' });
  try {
    const ws = await box.endpoint();
    console.log(`CDP endpoint: ${ws}`);
    // → ws://localhost:3000/...
  } finally {
    await box.stop();
  }
}

main();

For Puppeteer, use endpoint() which starts the browser with CDP. Do not call start() first — start() launches Playwright Server, which is a different (mutually exclusive) connection mode.

Connection modes

BrowserBox has two mutually exclusive connection modes:

Mode	Method	Protocol	Use with
Playwright Server	`playwright_endpoint()`	WebSocket	Playwright (all browsers)
Direct CDP/BiDi	`endpoint()`	WebSocket	Puppeteer, Selenium (chromium/firefox only)

Supported browsers

Browser	Works with Playwright	Works with Puppeteer
`chromium`	Yes	Yes (CDP)
`firefox`	Yes	Yes (WebDriver BiDi)
`webkit`	Yes	No

Step 2: Take a screenshot

Connect to the browser and capture a screenshot.

Python (Playwright)
Node.js (Puppeteer)

screenshot.py

import asyncio
from boxlite import BrowserBox, BrowserBoxOptions
from playwright.async_api import async_playwright


async def main():
    opts = BrowserBoxOptions(browser="chromium", memory=2048, cpu=2)
    async with BrowserBox(opts) as browser:
        ws = await browser.playwright_endpoint()

        async with async_playwright() as p:
            # Connect to the browser running inside the VM
            b = await p.chromium.connect(ws)
            page = await b.new_page()

            await page.goto("https://example.com")
            await page.screenshot(path="screenshot.png")
            print("Screenshot saved to screenshot.png")

            await b.close()


if __name__ == "__main__":
    asyncio.run(main())

screenshot.js

import { BrowserBox } from '@boxlite-ai/boxlite';
import puppeteer from 'puppeteer-core';

async function main() {
  const box = new BrowserBox({ browser: 'chromium' });
  try {
    const ws = await box.endpoint();

    // Connect to the browser running inside the VM
    const instance = await puppeteer.connect({ browserWSEndpoint: ws });
    const page = await instance.newPage();

    await page.goto('https://example.com');
    await page.screenshot({ path: 'screenshot.png' });
    console.log('Screenshot saved to screenshot.png');

    await instance.close();
  } finally {
    await box.stop();
  }
}

main();

Step 3: Scrape a page

Extract content from a web page using standard DOM queries.

Python (Playwright)
Node.js (Puppeteer)

scrape.py

import asyncio
from boxlite import BrowserBox, BrowserBoxOptions
from playwright.async_api import async_playwright


async def main():
    opts = BrowserBoxOptions(browser="chromium", memory=2048, cpu=2)
    async with BrowserBox(opts) as browser:
        ws = await browser.playwright_endpoint()

        async with async_playwright() as p:
            b = await p.chromium.connect(ws)
            page = await b.new_page()

            await page.goto("https://news.ycombinator.com")

            # Extract the top 5 story titles
            titles = await page.eval_on_selector_all(
                ".titleline > a",
                "elements => elements.slice(0, 5).map(e => e.textContent)"
            )

            print("Top 5 Hacker News stories:")
            for i, title in enumerate(titles, 1):
                print(f"  {i}. {title}")

            await b.close()


if __name__ == "__main__":
    asyncio.run(main())

scrape.js

import { BrowserBox } from '@boxlite-ai/boxlite';
import puppeteer from 'puppeteer-core';

async function main() {
  const box = new BrowserBox({ browser: 'chromium' });
  try {
    const ws = await box.endpoint();

    const instance = await puppeteer.connect({ browserWSEndpoint: ws });
    const page = await instance.newPage();

    await page.goto('https://news.ycombinator.com');

    // Extract the top 5 story titles
    const titles = await page.$$eval(
      '.titleline > a',
      (links) => links.slice(0, 5).map((a) => a.textContent)
    );

    console.log('Top 5 Hacker News stories:');
    titles.forEach((title, i) => {
      console.log(`  ${i + 1}. ${title}`);
    });

    await instance.close();
  } finally {
    await box.stop();
  }
}

main();

Step 4: Interact with a page

Read content, click links, and handle navigation.

Python (Playwright)
Node.js (Puppeteer)

interact.py

import asyncio
from boxlite import BrowserBox, BrowserBoxOptions
from playwright.async_api import async_playwright


async def main():
    opts = BrowserBoxOptions(browser="chromium", memory=2048, cpu=2)
    async with BrowserBox(opts) as browser:
        ws = await browser.playwright_endpoint()

        async with async_playwright() as p:
            b = await p.chromium.connect(ws)
            page = await b.new_page()

            await page.goto("https://example.com")

            # Get page title and content
            title = await page.title()
            heading = await page.text_content("h1")
            print(f"Title: {title}")
            print(f"Heading: {heading}")

            # Click a link
            await page.click("a")
            print(f"Navigated to: {page.url}")

            await b.close()


if __name__ == "__main__":
    asyncio.run(main())

interact.js

import { BrowserBox } from '@boxlite-ai/boxlite';
import puppeteer from 'puppeteer-core';

async function main() {
  const box = new BrowserBox({ browser: 'chromium' });
  try {
    const ws = await box.endpoint();

    const instance = await puppeteer.connect({ browserWSEndpoint: ws });
    const page = await instance.newPage();

    await page.goto('https://example.com');

    // Get page title and content
    const title = await page.title();
    const heading = await page.$eval('h1', (el) => el.textContent);
    console.log(`Title: ${title}`);
    console.log(`Heading: ${heading}`);

    // Click a link
    await page.click('a');
    console.log(`Navigated to: ${page.url()}`);

    await instance.close();
  } finally {
    await box.stop();
  }
}

main();

BrowserBox allocates 2 CPUs and 2048 MiB of memory by default. Increase these if your pages are heavy or you’re running multiple tabs.

What’s next?

Connect to an LLM

Give your LLM agent the ability to browse the web by combining BrowserBox with function calling.

BrowserBox API reference

Full API docs for BrowserBox, BrowserBoxOptions, and connection endpoints.

AI agent integration

Production patterns for using BoxLite with AI agents.

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

What you’ll build

Prerequisites

Step 1: Launch a BrowserBox

Connection modes

Supported browsers

Step 2: Take a screenshot

Step 3: Scrape a page

Step 4: Interact with a page

What’s next?

Connect to an LLM

BrowserBox API reference

AI agent integration

​What you’ll build

​Prerequisites

​Step 1: Launch a BrowserBox

​Connection modes

​Supported browsers

​Step 2: Take a screenshot

​Step 3: Scrape a page

​Step 4: Interact with a page

​What’s next?

Connect to an LLM

BrowserBox API reference

AI agent integration

What you’ll build

Prerequisites

Step 1: Launch a BrowserBox

Connection modes

Supported browsers

Step 2: Take a screenshot

Step 3: Scrape a page

Step 4: Interact with a page

What’s next?