Skip to main content
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 the right choice 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 so in where the traffic comes from. 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 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 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.
Ask the tool for its own guide instead of a docs page. It serves version-matched instructions, so they are never stale. The agents on a machine run 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-open all use 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 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-open and $BROWSER open in this browser, on the desktop.
  • It forks and sleeps with the machine. A fork taken mid-session continues on the copy, logins included.
From a script, 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.

With the client utilities enabled 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:
The agent attaches with --cdp:
With --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.
A coding agent needs none of this. In a session opened from a laptop 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:
In an automation, 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 local reports 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.
Label your laptops so an agent can name them. Run boxd config set client-utils.label "desktop" on each one.

From scripts

Both return a standard Playwright Browser 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.