Launch a Browser

Every machine ships its own browser, built for agents and visible on the machine’s Desktop. That is the one to use. The client utilities also let a machine drive a Chrome on your laptop, which is worth reaching for in one specific case: when the request has to come from your network. Both are driven the same way; they differ in where they run and, therefore, where the traffic comes from.

	The machine’s browser	Your Chrome on your laptop
Runs	on the machine, on its Desktop	on your computer, on your screen
Profile	its own, persistent; extra isolated sessions on demand	a dedicated boxd profile on your laptop, separate from your everyday Chrome; persistent, so log in once
Anti-bot fingerprinting	on	none
Watch and take over	Open → Desktop in the console, or the link the agent gives you	it’s on your screen
Needs	nothing, it ships in the image	client utilities enabled (macOS or Linux)
Works from	any machine with a desktop	your personal and private machines only

Rule of thumb: use the machine’s browser; use your laptop’s when the request has to come from your network. A site that blocks datacenter IPs, a service reachable only through your VPN, an account pinned to an IP allow-list, geo-restricted content: those are its job. Otherwise the machine’s browser is faster to reach (nothing to install, nothing to keep awake) and you can still take part - the agent hands you the Desktop link, and you log in, approve or solve the captcha in the browser it already opened there. Needing a human mid-task is not a reason to switch browsers. One thing not to expect from your laptop’s browser: your existing logins. It runs in a dedicated boxd profile, separate from your everyday Chrome, so it starts signed out. Logins you make in it do persist. The coding agents on every machine are given exactly this guidance.

The machine’s browser

Every machine ships agent-browser, a browser-automation CLI built for agents, backed by a Chromium build with anti-bot fingerprinting. It opens on the machine’s desktop, so whoever owns the machine can watch, and click into, what the agent is doing live.

agent-browser skills get core      # the usage guide, served by the tool itself
agent-browser open https://example.com

Ask the tool for its own guide rather than a docs page: it serves version-matched instructions, so they are never stale. Agents are told to run agent-browser skills get core before their first browsing session. Behaviour worth knowing:

One shared, persistent session. By default everything, the agent, the console’s Browser tile, links opened with xdg-open, uses the same browser window and profile, named default. Cookies and logins survive closing the browser, relaunches and crashes. Log in once and stay logged in.
Isolated sessions on demand. Set AGENT_BROWSER_SESSION=<name> to get a separate window with its own profile: a second account, a clean slate, or parallel work.
Opens the desktop for you. Starting the browser starts the desktop if it’s dormant. Share the link, https://app.boxd.sh/desktop/<machine-name>, so the owner can watch.
Any URL lands here. xdg-open and $BROWSER open in this browser, on the desktop.
It forks and suspends with the machine. A fork taken mid-session continues on the copy, logins included.

From a script, the same browser is available to Playwright as browser.launch() in @boxd/run. See Browsers in automations.

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

Your Chrome on your laptop

With the client utilities enabled on your computer (boxd config set client-utils.enable true), a machine can start and drive a Chrome on your laptop, on your screen. It runs in a dedicated profile that boxd keeps on your computer (~/.boxd/browser-sessions/default/), separate from your everyday Chrome, so it starts empty; whatever you log in to there stays logged in across sessions. Only your personal and private machines can do this; shared and isolated machines are refused.

boxd local devices                                       # which computers are connected? (the default is marked)
boxd local browser open                                  # start Chrome on your laptop, visibly
boxd local browser open --headless                       # start it invisibly
boxd local browser cdp-url                               # the CDP endpoint, one line
boxd local browser info                                  # running? plus the endpoint
boxd local browser close

The agent attaches with --cdp:

agent-browser --cdp "$(boxd local browser cdp-url)" snapshot

With --cdp, none of the machine-side behaviour applies: no desktop, no stealth, no named sessions. It’s the one browser on your laptop, and its state is whatever it already is.

Connecting via CDP

boxd local browser cdp-url prints a Chrome DevTools Protocol endpoint any CDP client inside the machine can use. It prints even before the browser is running; run open first if you want the window visible on your screen (attaching to a browser that isn’t running starts a headless one).

// Playwright
const { chromium } = require("playwright-core");
const { execSync } = require("child_process");
const ws = execSync("boxd local browser cdp-url", { encoding: "utf8" }).trim();
const browser = await chromium.connectOverCDP(ws);
const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });

// Puppeteer
const puppeteer = require("puppeteer-core");
const browser = await puppeteer.connect({ browserWSEndpoint: ws });

Or from a coding agent: in a session opened from a computer with client utilities enabled, a chrome-devtools MCP server pointed at this browser is registered automatically in Claude Code, Codex and OpenCode inside the machine, so this works out of the box:

claude
# open my local browser and search for cat pictures on google

In an automation, boxd.local.device().browser.connect() does all of this and hands you a Playwright Browser.

Several computers

Agents are told to check first and ask:

Several computers connected? Don’t guess. Ask which one, then target it: boxd local --device <label|id> browser open.
None connected, or boxd local reports a missing feature? Ask the user to install or update the CLI and enable client utilities; use the machine’s browser meanwhile.

Label your computers so an agent can name them: boxd config set client-utils.label "desktop" on each one.

From scripts

Both browsers return a standard Playwright Browser in an automation: browser.launch() for the machine’s, boxd.local.device().browser.connect() for your laptop’s.

Getting started

Guides

Integrations & automations

Use cases

References

Launch a Browser

The machine’s browser

Your Chrome on your laptop

Connecting via CDP

Several computers

From scripts

​The machine’s browser

​Your Chrome on your laptop

​Connecting via CDP

​Several computers

​From scripts

The machine’s browser

Your Chrome on your laptop

Connecting via CDP

Several computers

From scripts