Browsers

@boxd/run gives a script two browsers, both driven with Playwright. You get a standard Playwright Browser back, and everything after that is ordinary Playwright: pages, locators, screenshots, downloads. The broader picture, what a coding agent should use, agent-browser, the desktop, is on Launch a Browser.

This machine’s browser: `browser.launch()`

import { browser } from "@boxd/run";

const b = await browser.launch();          // headed on the machine's Desktop, stealth on
const page = await b.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await b.close();

Visible by default. The browser opens on the machine’s Desktop. Open the machine in the console and choose Open → Desktop to watch it, and click into it to help (type a password, solve a captcha). The desktop is brought up automatically. Pass { headless: true } for an invisible run.
Stealth by default. The machine ships a Chromium build with anti-bot fingerprinting, and every launch gets a fresh fingerprint. Pass { stealth: false } to turn it off.
Playwright options pass through. proxy, timeout, args, and so on are accepted. Your args are added last, so they win, and excludeArgs drops any default you don’t want.
Don’t set a viewport for the headed browser. It’s a real on-screen window, so contexts default to viewport: null. Pass one only if you specifically want emulation.

Each launch starts with a clean profile. For a persistent, logged-in profile on the machine, use the desktop’s own browser via agent-browser. See Launch a Browser.

Your laptop’s browser: `boxd.local.device().browser.connect()`

import { boxd } from "@boxd/run";

const laptop = boxd.local.device();               // the laptop that ran `run`, or your newest-connected one
const b = await laptop.browser.connect();         // starts Chrome on it if needed, then attaches
const page = await b.newPage();
await page.goto("https://mail.google.com");       // the boxd profile on your laptop; log in once, it persists

This drives a Chrome on your own computer, on your own screen and network, in a dedicated profile that boxd keeps separate from your everyday Chrome (log in once and it persists). It needs the client utilities enabled on that computer (boxd config set client-utils.enable true), and it only works from your personal and private machines, never from shared or isolated ones.

connect() opens the browser headed (visible on your screen) unless you pass { headless: true }.
Several computers connected? await boxd.local.devices() lists them. boxd.local.device("desktop") picks one by label, id or unique prefix and never falls back to another.
Lower-level: laptop.browser.open(), .info(), .cdpUrl() and .close() are there if you want to drive the CDP endpoint with a different client.

If no laptop is reachable, the call fails with device not connected. A script with no laptop context at all gets no laptop in this context - pick one explicitly: await local.devices() lists them, local.device("<label|id>") binds one. When the browser doesn’t come up, the message says client utilities must be enabled on it.

Which one?

browser.launch() is the default. Reach for the laptop only in the row that names it.

Need	Use
Anything ordinary: scraping, forms, screenshots, checking a page	this machine’s browser
Isolation, a clean profile, stealth, many in parallel	this machine’s browser
Someone to act mid-task (log in, approve, solve a captcha)	this machine’s browser: open its Desktop and act in the browser the script opened
The request must come from your network: datacenter IPs blocked, a VPN-only service, an IP allow-list, geo-restricted content	your laptop’s browser

Note what is not a reason to use your laptop’s browser: getting at your logins. It runs in a dedicated boxd profile, separate from your everyday Chrome, so it starts signed out. Background jobs that reach your laptop keep addressing the computer you started them from, across restarts. That still makes a scheduled automation depend on that laptop being awake and online at 3am, which is another reason to prefer the machine’s own browser for anything unattended.

Getting started

Guides

Integrations & automations

Use cases

References

This machine’s browser: `browser.launch()`

Your laptop’s browser: `boxd.local.device().browser.connect()`

Which one?

​This machine’s browser: browser.launch()

​Your laptop’s browser: boxd.local.device().browser.connect()

​Which one?

This machine’s browser: `browser.launch()`

Your laptop’s browser: `boxd.local.device().browser.connect()`

Which one?