Rule of thumb: use the machine’s browser, and use your laptop’s when the request has to come from your network. That covers a site that blocks datacenter IPs, a service reachable only through your VPN, an account pinned to an IP allowlist, and geo-restricted content. Otherwise the machine’s browser is faster to reach, with nothing to install and 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.
Do not expect your existing logins in your laptop’s browser. It runs in a dedicated boxd profile, separate from your everyday Chrome, so it starts signed out. Logins you make in it persist. The coding agents on every machine follow this same guidance.
The machine’s browser
Every machine shipsagent-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 the machine’s owner, or any org member when the machine is shared, can watch what the agent is doing live and click into it.
agent-browser skills get core before their first browsing session.
Behavior worth knowing:
- One shared, persistent session. By default the agent, the console’s Browser tile and links opened with
xdg-openall use the same browser window and profile, nameddefault. 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 is dormant. Share the link,
https://app.boxd.sh/desktop/<machine>, so the people with access to the machine can watch. - Any URL lands here.
xdg-openand$BROWSERopen in this browser, on the desktop. - It forks and sleeps with the machine. A fork taken mid-session continues on the copy, logins included.
browser.launch() in @boxd/run opens a separate Playwright-controlled browser on the same desktop. It starts with a clean profile on every launch and does not share the persistent session above. See Browsers.
For a GUI app that isn’t a web page, or a page these tools can’t work with, an agent can use computer use on the same desktop: screenshots, the mouse and the keyboard.
Your Chrome on your laptop
One command inside the machine, and a real Chrome opens on your laptop.
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 laptop (~/.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 private machines can do this. Shared and isolated machines are refused.
Inside a machine:
--cdp:
--cdp, none of the machine-side behavior applies: no desktop, no stealth, no named sessions. It is 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, because attaching to a browser that isn’t running starts a headless one.
chrome-devtools MCP server pointed at this browser is registered automatically in Claude Code, Codex and OpenCode inside the machine:
boxd.local.device().browser.connect() does all of this and hands you a Playwright Browser.
Several laptops
Agents on the machine check which laptops are connected before they open a browser:- Several laptops connected. The agent asks which one, then targets it from inside the machine with
boxd local --device <label|id> browser open. - None connected, or
boxd localreports a missing feature. The agent asks you to install or update the CLI and enable client utilities, and uses the machine’s browser in the meantime.
boxd config set client-utils.label "desktop" on each one.
From scripts
Both return a standard PlaywrightBrowser in an automation: browser.launch() for a clean-profile browser on the machine’s desktop, and boxd.local.device().browser.connect() for your laptop’s.