> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser usage

> Headless Chrome on every machine, plus a way to drive the real Chrome on your Mac from inside a VM.

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](/guides/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](/guides/fork) of a machine mid-crawl continues the crawl on the copy.

<Frame caption="One command inside the VM, and a real Chrome opens on your Mac.">
  <video autoPlay muted loop playsInline src="https://mintcdn.com/azin/psRZbQh2QwMUVL3U/videos/local-browser.mp4?fit=max&auto=format&n=psRZbQh2QwMUVL3U&q=85&s=4e62bdee02703882c6162b681be159c4" data-path="videos/local-browser.mp4" />
</Frame>

## 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:

```bash theme={"theme":"github-dark"}
boxd config set client-utils.enable true   # once, on your Mac
```

```bash theme={"theme":"github-dark"}
# 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:

```javascript theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
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.

<Info>
  The local browser builds on the [client utilities](/guides/client-utilities), currently available for macOS (Apple Silicon). The full reference is in [Launch a Browser](/guides/launch-a-browser).
</Info>

## 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.