Skip to main content
boxd client tools run on your Mac (Linux support coming soon) and bridge local resources into your VMs. Once installed, you can read files from your local filesystem and control a local Chrome browser — all from inside a VM.

​
Install

curl -fsSL https://boxd.sh/downloads/install.sh | sh
This installs the boxd-clientd daemon and configures SSH to start it automatically when you connect to boxd.
Currently available for macOS (Apple Silicon) only.

​
How it works

When you SSH into a boxd machine, the client daemon starts on your Mac and an SSH tunnel is established. Inside the VM, the boxd local commands communicate with the daemon through this tunnel. No configuration needed — it works automatically after install.

​
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 and macOS temporary directories (e.g. /var/folders/) are accessible. System files outside these areas are blocked.

​
Full Disk Access

Some macOS temporary directories (like TemporaryItems used for screenshots) are protected by TCC permissions. If you get “Operation not permitted” errors reading files in /var/folders/, you need to grant Full Disk Access to boxd-clientd. This is optional — only needed if you want to read screenshots or other TCC-protected files from your VM.
1

Open System Settings

Go to System Settings → Privacy & Security → Full Disk Access.
2

Add boxd-clientd

Click the + button. In the Finder dialog, navigate to:
~/Applications/boxd-clientd.app
If you don’t see it, press Cmd+Shift+G and paste the path above. Click Open.
3

Enable

Toggle boxd-clientd on in the list.
4

Restart the daemon

launchctl stop sh.boxd.clientd
launchd will automatically restart it with the new permissions.

​
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

The CDP WebSocket URL is always the same: 
ws://$BOXD_CLIENTD_ADDR/browser/ws
Connect from Puppeteer: 
const puppeteer = require('puppeteer-core');

const browser = await puppeteer.connect({
  browserWSEndpoint: `ws://${process.env.BOXD_CLIENTD_ADDR}/browser/ws`
});

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 browser = await chromium.connectOverCDP(
  `ws://${process.env.BOXD_CLIENTD_ADDR}/browser/ws`
);
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

To update to the latest version, re-run the install command: 
curl -fsSL https://boxd.sh/downloads/install.sh | sh
The installer automatically restarts the daemon with the new version. If boxd local commands inside a VM show a message about updating, it means the daemon on your Mac is missing features available in the latest version.