Browser usage

Browser work on boxd comes in two shapes. Every machine ships headless Chrome for automation that runs entirely in the cloud, and the client utilities let a machine drive the real Chrome on your Mac, with your logged-in sessions, from inside the VM.

	Headless Chrome on the machine	Your Chrome on your Mac
Runs on	the boxd machine	your laptop
Sessions and logins	fresh, per machine	your real browser profile
Good for	scraping, screenshots, UI tests, agent verification	tasks that need your logged-in accounts, watching the agent browse
Needs	nothing, it ships in the image	client utilities enabled (macOS Apple Silicon)

Headless Chrome on the machine

Every machine’s image includes headless Chrome, so browser automation runs without downloading a browser first. Puppeteer and Playwright work the way they do on any Linux server, and anything they produce (screenshots, PDFs, scraped data) lands on the machine’s persistent disk. Agents drive it through a chrome-devtools MCP, which is pre-configured on every machine. That gives a coding agent a way to check its own UI work. It loads the app at the machine’s own *.boxd.sh URL, takes a before screenshot, makes the change, then captures the after screenshot and compares the two. Because the browser runs inside the VM, it forks and suspends with everything else. A fork of a machine mid-crawl continues the crawl on the copy.

One command inside the VM, and a real Chrome opens on your Mac.

Your Chrome, driven from a machine

Sometimes the task needs your browser, because that is where your sessions live. Turn on the client utilities on your Mac, then launch and control your local Chrome from inside any machine:

boxd config set client-utils.enable true   # once, on your Mac

# inside the VM
boxd local browser open          # launches Chrome on your Mac, prints a CDP URL
boxd local browser info          # status and the CDP URL again
boxd local browser close

The printed WebSocket URL is a Chrome DevTools Protocol endpoint forwarded to the Chrome on your Mac. Point Puppeteer or Playwright at it from inside the VM:

const { chromium } = require('playwright-core');
const { execSync } = require('child_process');

const out = execSync('boxd local browser open', { encoding: 'utf8' });
const wsUrl = out.match(/CDP WebSocket: (\S+)/)[1];

const browser = await chromium.connectOverCDP(wsUrl);

Claude Code can do the same conversationally, since the chrome-devtools MCP comes pre-configured:

claude
# "open my local browser and check whether the staging login flow still works"

The browser uses a fixed session directory on your Mac, so cookies and login state persist across open and close. One browser instance runs at a time, and calling open again returns the existing session.

The local browser builds on the client utilities, currently available for macOS (Apple Silicon). The full reference is in Launch a Browser.

Picking between the two

Use headless Chrome on the machine for anything repeatable and unattended: crawls, test suites, screenshot pipelines, agent self-verification. Use your local Chrome when the task depends on accounts you’re signed into, or when you want to watch what an agent is doing in a real browser window.

Getting started

Guides

Use cases

References

Browser usage

Headless Chrome on the machine

Your Chrome, driven from a machine

Picking between the two

​Headless Chrome on the machine

​Your Chrome, driven from a machine

​Picking between the two

Headless Chrome on the machine

Your Chrome, driven from a machine

Picking between the two