Client Utilities

boxd client tools run on your Mac (Windows support coming soon) and bridge local resources into your VMs. Once enabled, you can paste images into Claude Code, read files from your local filesystem, and control a local Chrome browser — all from inside a VM.

Enable

The client utilities are built into the boxd CLI from the Quickstart — there’s no separate download. They’re off by default; turn them on once per machine with:

boxd config set client-utils.enable true

This installs a small background agent (a launchd agent on macOS) and registers this device with boxd. Manage it any time with:

boxd config get client-utils.enable         # is it enabled and running?
boxd config set client-utils.enable false   # stop and remove the agent

Currently available for macOS (Apple Silicon) only.

How it works

boxd config set client-utils.enable true registers your machine under a device id and starts a background agent that keeps a connection open to boxd. Every VM you enter with boxd connect or ssh <vm>.boxd carries that device id, so the boxd local commands inside the VM route back to your machine through boxd — no per-connection setup, and it keeps working across reconnects. Run boxd config get client-utils.enable to confirm it’s enabled and running.

Clipboard and image pasting

With client tools enabled, you can paste images from your Mac’s clipboard directly into Claude Code running inside a VM. This works via an xclip shim that intercepts clipboard reads and routes them through boxd to your Mac’s clipboard. This is especially useful for sharing screenshots, diagrams, or UI mockups with Claude Code without manually transferring files.

Reading local files

List and read files on your local machine from inside a VM:

boxd local ls                              # List your home directory
boxd local ls Documents                    # Relative to home
boxd local ls /Users/you/Desktop           # Absolute path
boxd local read ~/notes.txt                # Read a file
boxd local read ~/app.log --tail=50        # Last 50 lines
boxd local read ~/app.log --head=20        # First 20 lines
boxd local read ~/app.log --range=10:30    # Lines 10 through 30

Output from ls shows absolute paths with type and size:

dir   /Users/you/Documents
file  /Users/you/.bashrc (1234 bytes)

All commands accept --json for structured output.

Path access

For security, only files under your home directory are accessible. Paths outside it are blocked.

Browser

Launch and control a Chrome instance on your Mac, with the Chrome DevTools Protocol (CDP) forwarded into the VM. This lets tools like Puppeteer or Playwright running inside a VM control a real browser on your local machine.

boxd local browser open                    # Launch Chrome
boxd local browser open --headless         # Launch headless
boxd local browser info                    # Check status and CDP URL
boxd local browser close                   # Close the browser

Connecting via CDP

boxd local browser open (and boxd local browser info) print the CDP WebSocket URL — it points at boxd’s device ingress (…/device/<id>/browser/ws) and is forwarded to the Chrome instance on your machine. Pass that URL to Puppeteer or Playwright. Connect from Puppeteer:

const puppeteer = require('puppeteer-core');
const { execSync } = require('child_process');

// Launches Chrome on your machine and prints "CDP WebSocket: <url>".
const out = execSync('boxd local browser open', { encoding: 'utf8' });
const wsUrl = out.match(/CDP WebSocket: (\S+)/)[1];

const browser = await puppeteer.connect({ browserWSEndpoint: wsUrl });
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });

Or from Playwright:

const { chromium } = require('playwright-core');
const { execSync } = require('child_process');

const out = execSync('boxd local browser open', { encoding: 'utf8' });
const wsUrl = out.match(/CDP WebSocket: (\S+)/)[1];

const browser = await chromium.connectOverCDP(wsUrl);

Or straight from chrome using the pre-installed and pre-configured chrome-devtools-mcp:

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

Session persistence

The browser uses a fixed session directory on your Mac (~/.boxd/browser-sessions/default/). Cookies, localStorage, and login state persist across open/close cycles. Only one browser instance runs at a time. Calling open when a browser is already running returns the existing session.

Updating

Re-run the boxd install command to update — it upgrades the boxd CLI in place. The next time you run boxd, the client agent automatically restarts on the new version. If boxd local commands inside a VM show a message about updating, it means the agent on your machine is missing features available in the latest version.

Getting started

Cloud dev boxes

Preview environments

Agents on boxd

Organizations

Integrations

How it works

Reference

Client Utilities

Enable

How it works

Clipboard and image pasting

Reading local files

Path access

Browser

Connecting via CDP

Session persistence

Updating

​Enable

​How it works

​Clipboard and image pasting

​Reading local files

​Path access

​Browser

​Connecting via CDP

​Session persistence

​Updating

Enable

How it works

Clipboard and image pasting

Reading local files

Path access

Browser

Connecting via CDP

Session persistence

Updating