Skip to main content
The client utilities are a small background agent on your laptop that lets your machines reach back to it. From inside a machine you can paste images from your clipboard into Claude Code, read files under your home directory, and start and drive a Chrome on your laptop. That Chrome runs in a dedicated profile that starts empty, so it does not have your existing logins.

Enable

The client utilities are built into the boxd CLI. See Installation. There is no separate download, and they are off by default. On each laptop you want to reach:
You need to be logged in first (boxd auth login). Run it as yourself, not with sudo. The agent runs in your login session so it can reach your clipboard, browser and home directory. macOS and Linux are supported. These settings are all changed on your laptop:
Turning the utilities off keeps a small background agent running in a reduced mode that only syncs your ~/.ssh/config entries. Running boxd config set daemon.enable false on your laptop removes it altogether.

Which machines can reach your laptop

Your private machines, the ones only you have a shell on. Shared machines and isolated machines are refused, so a teammate on a shared machine can never read your files or drive your browser. Every session you open with boxd connect or ssh <machine>.boxd is tied to the laptop you opened it from. A background automation reaches the laptop it was started from. A session with no laptop attached, such as a console terminal or a cron job, reaches your most recently connected laptop instead. Nothing else is needed, and the bridge keeps working across reconnects.

Several laptops

Enable the utilities on each one, and give them labels. Then, inside a machine:
The listing marks the most recently connected laptop as the default. A session you opened from one of your laptops (boxd connect, ssh <machine>.boxd) goes to that laptop, and so does an automation started from that session. A session with no laptop attached (cron, the console terminal) goes to the marked default. Every boxd local command takes --device <label|id|prefix> to target a specific laptop. An explicit choice is strict and never falls back to a different one, and an ambiguous prefix is refused. Agents on the machine run boxd local devices first and ask which laptop when there is more than one.

Clipboard and image pasting

With the utilities enabled, pasting into Claude Code inside a machine pulls from your laptop’s clipboard, images included. Screenshots, diagrams and mockups go straight into the conversation with no file transfer.

Reading local files

Inside a machine:
Access is read-only and limited to files under your home directory. Anything outside it is refused. Files up to 100 MiB can be read. All commands except read accept --json.

Browser

Start and control a Chrome on your laptop from a machine. The browser runs on your screen and your network, in a dedicated profile boxd keeps for it, separate from your everyday Chrome. It starts empty. Log in once and it stays logged in. Inside a machine:
Chrome or Chromium must be installed on the laptop. One instance runs at a time, and open while it is running returns the existing one. Its profile lives in ~/.boxd/browser-sessions/default/ on your laptop, so cookies and logins persist across open and close.

Driving it

boxd local browser cdp-url prints a Chrome DevTools Protocol endpoint that any CDP client inside the machine can use: the pre-installed agent-browser (agent-browser --cdp "$(boxd local browser cdp-url)"), Playwright, Puppeteer, or the chrome-devtools MCP server that coding agents get automatically. In an automation, boxd.local.device().browser.connect() hands you a Playwright Browser. For examples, and how this compares with the machine’s own browser, see Launch a browser.

Errors you might see

  • no devices connected - on your computer, run `boxd config set client-utils.enable true` : nothing is enabled, or the agent on your laptop isn’t running.
  • can't reach your computer from this VM - the boxd client daemon isn't connected: re-run the enable command on your laptop.
  • this feature requires an updated boxd client on your computer: the agent is older than the machine expects. Update the CLI on your laptop.
  • client utilities are not available on org-shared VMs or client utilities are not available on isolated VMs: this is by design. Fork the shared machine to get a private copy.

Update

Re-run the install command on your laptop to upgrade the boxd CLI in place. See Installation. The next time you run boxd, the agent restarts on the new version.