Skip to content
Back to search

boxery

Self-hosted desktop VMs your coding agents can drive (pi extension + MCP server). More computers for your agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/modem-dev/boxery with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/modem-dev/boxery'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/benvinegar--boxery/badge.svg)](/listings/benvinegar--boxery)

HTML

<a href="/listings/benvinegar--boxery"><img src="/api/listings/benvinegar--boxery/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

On a **Linux host** with KVM and libvirt ([full requirements](docs/install.md#linux-host-libvirtkvm)):

npm install -g boxery-vm
boxery-host init                 # storage pool, LLM proxy, lease reaper, ~/.local/bin symlinks
boxery-host build-base           # golden desktop image (~3 min, one time)

On **your laptop**:

npm install -g boxery-vm            # the boxery CLI + boxery-mcp
boxery setup you@my-host         # checks ssh, registers your key

pi install npm:boxery-vm            # the pi extension
pi --vm demo                     # pi with a VM named "demo" (created if missing)

Then ask: *"Clone my repo in the VM, start the dev server, and screenshot the homepage in Chrome."*

> **Only have a Mac?** Run the host on the Mac itself with Lima: `boxery-host init --backend lima` and `boxery setup local`. See [Install → macOS](docs/install.md#macos-host-lima).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 200 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/lockup-dark.svg">
  4. <img src="docs/brand/lockup-light.svg" alt="boxery" width="220">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. Easiest way to give your coding agents VMs
  9. </p>
  10. <p align="center">
  11. <a href="https://github.com/modem-dev/boxery/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/modem-dev/boxery/actions/workflows/ci.yml/badge.svg"></a>
  12. <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue">
  13. <a href="https://www.npmjs.com/package/boxery-vm"><img alt="npm" src="https://img.shields.io/npm/v/boxery-vm?logo=npm"></a>
  14. <a href="docs/install.md#choosing-a-backend"><img alt="OS: macOS | Linux" src="https://img.shields.io/badge/os-macOS%20%7C%20Linux-lightgrey"></a>
  15. <a href="docs/mcp.md"><img alt="MCP 2025-11-25" src="https://img.shields.io/badge/MCP-2025--11--25-6f42c1?logo=modelcontextprotocol&logoColor=white"></a>
  16. </p>
  17. <p align="center">
  18. <a href="docs/install.md"><b>Install</b></a> ·
  19. <a href="docs/mcp.md">MCP server</a> ·
  20. <a href="docs/pi-extension.md">pi extension</a> ·
  21. <a href="docs/cli.md">CLI</a> ·
  22. <a href="host/backends/README.md">Backends</a> ·
  23. <a href="docs/README.md">All docs</a>
  24. </p>
  25. <p align="center">
  26. <picture>
  27. <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/hero-dark.svg">
  28. <img src="docs/diagrams/hero-light.svg" alt="Coding agents on your machine (Claude Code, Codex, Cursor, opencode, pi) use boxery to spin up, fork, snapshot and throw away VMs and run code, Chrome and desktops inside them: locally, on a remote box, or in the cloud. VMs are drawn as cubes whose look shows their state" width="680">
  29. </picture>
  30. <br>
  31. <a href="docs/install.md#choosing-a-backend">
  32. <picture>
  33. <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/works-with-dark.svg">
  34. <img src="docs/diagrams/works-with-light.svg" alt="Works with Lima on macOS; libvirt, Cloud Hypervisor and OpenShell on Linux; exe.dev and boat.dev in the cloud" width="760">
  35. </picture>
  36. </a>
  37. </p>
  38. ---
  39. > [!WARNING]
  40. > **Early-stage, experimental software.** Expect rough edges and breaking changes between releases.
  41. boxery lets your agents manage their own Linux VMs: on your Mac, a Linux server, a sandbox provider like exe.dev or boat.dev, or all of them at once. Your agent stays on your machine with your login and setup; the VM is where it works, and your keys never go in.
  42. ## Quick start
  43. Give this prompt to your agent:
  44. ```text
  45. Read github.com/modem-dev/boxery and set up boxery on this machine.
  46. Then spin up a VM with `boxery new demo` and open its desktop.
  47. ```
  48. Prefer to do it by hand? See [Install](#install).
  49. ## What it's for
  50. - **Dev boxes.** A full Linux machine per project or branch. `ssh demo.boxery`, or open it in VS Code.
  51. - **Safe sandboxes.** Let an agent install anything and run code you don't trust, away from your laptop and your keys.
  52. - **Parallel attempts.** Fork a running VM, try three fixes at once, keep the one that works.
  53. - **Browser and desktop tasks.** Chrome, clicks and screenshots on a real desktop you can watch live.
  54. - **Always-on agents and long jobs.** Run them on a server or in the cloud, and they keep going after you close your laptop.
  55. ## Why boxery
  56. - **Built for agents.** Agents create, fork and drive VMs themselves over [MCP](docs/mcp.md): Claude Code, Codex, Cursor, opencode or any MCP client, plus a native [pi](docs/pi-extension.md) extension.
  57. - **Fast.** A full desktop VM in about 13 s on libvirt, or a [headless](docs/cli.md#lifecycle) one with no desktop at all. Snapshot a running VM in about 1 s on libvirt.
  58. - **Mix VM providers.** One MCP server drives your Mac, a Linux server and sandbox providers (exe.dev, boat.dev) [at once](docs/hosts.md), with the same tools on each.
  59. - **Your credentials never enter a VM.** VMs get a revocable token, and the host swaps in your real key. A VM gets nothing by default, not even an LLM, until you [grant it](docs/grants.md).
  60. ## How it works
  61. - **On your machine**, the boxery MCP server (or pi extension) gives your agent the `vm_*` tools.
  62. - **The boxery host** is a machine you run: your Mac, a Linux box, or a small VPS for cloud VMs. The tools reach it over ssh. It holds your keys and grants, and creates, forks and wipes VMs.
  63. - **The VMs** are untrusted. They run anything, and hold only a revocable token that the host swaps for your real key.
  64. Your machine and the host can be the same one. [Security model →](docs/security.md)
  65. <p align="center">
  66. <picture>
  67. <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/host-dark.svg">
  68. <img src="docs/diagrams/host-light.svg" alt="Coding agents reach the trusted boxery host over ssh. The host holds your real LLM keys and API tokens and runs the credential proxy, grants, leases and pool, and images and forks. It creates, forks and wipes untrusted VMs on Lima, libvirt, exe.dev or boat.dev, and each VM holds only a revocable token that the proxy swaps for your real key." width="680">
  69. </picture>
  70. </p>
  71. ## Platforms
  72. The host runs VMs on your Mac, on Linux, or in the cloud. Each backend is a stack of existing tools, and boxery drives the top of it, so agents get the same tools on every one except OpenShell. One MCP server can drive several hosts [at once](docs/hosts.md). [Choosing a backend →](docs/install.md#choosing-a-backend)
  73. <p align="center">
  74. <picture>
  75. <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/layers-dark.svg">
  76. <img src="docs/diagrams/layers-light.svg" alt="What runs a boxery VM, layer by layer. The boxery host is the orchestrator over every backend. On macOS, Lima (local): limactl manages Apple's Virtualization.framework, on the macOS kernel's hypervisor, on Apple silicon. On Linux: libvirt (fastest) manages QEMU; Cloud Hypervisor (minimal, experimental) is managed by boxery itself, with a systemd unit per VM; both run on KVM in the Linux kernel. OpenShell (restricted, experimental) goes through its gateway to a container that shares the host kernel, with no VM. In the cloud, exe.dev and boat (experimental), with no hardware, are reached through their API, and the rest runs on their servers." width="680">
  77. </picture>
  78. </p>
  79. - **macOS: Lima.** VMs on the Mac you're on, through Apple's Virtualization framework. The quickest way to try boxery, and everything stays local.
  80. - **Linux: libvirt.** QEMU on KVM, and the fastest backend. Use a physical machine: a desktop, a laptop or a home server. A VPS works only if it offers nested virtualization.
  81. - **Cloud: exe.dev.** VMs on exe.dev, with no hardware of your own. The host keeps a tunnel to each VM, so put it on an always-on machine such as a small VPS, and use your laptop as a controller.
  82. ### Experimental
  83. - **Linux: Cloud Hypervisor.** A leaner VMM on the same KVM, with no libvirt: boxery manages it itself, with a systemd unit per VM.
  84. - **Linux: [OpenShell](docs/openshell.md).** Headless sandboxes from [NVIDIA's OpenShell](https://github.com/NVIDIA/OpenShell), behind its gateway, with a policy on what each one can read and reach. With its Docker driver they're containers on the host's kernel, not VMs. No desktop, snapshots, forks or pool.
  85. - **Cloud: boat.dev.** VMs on boat.dev, with no hardware of your own. For long-running work, keep the host on an always-on machine such as a small VPS.
  86. ## Install
  87. The easiest way is to give this prompt to your agent:
  88. ```text
  89. Read github.com/modem-dev/boxery and set up boxery on this machine.
  90. Then spin up a VM with `boxery new demo` and open its desktop.
  91. ```
  92. Or by hand, on a Mac:
  93. ```bash
  94. brew install lima jq node # jq: the Lima backend reads limactl's JSON with it
  95. npm install -g boxery-vm
  96. boxery-host init --backend lima && boxery-host build-base
  97. boxery setup local
  98. ```
  99. `build-base` builds the desktop image once (about 3 min); skip it if you only want headless VMs. On Linux or in the cloud, see the [install guide](docs/install.md#choosing-a-backend).
  100. Then connect your agent:
  101. ```bash
  102. npx add-mcp boxery-vm # Claude Code, Codex, Cursor, VS Code, opencode, Zed, …
  103. pi install npm:boxery-vm # or the native pi extension
  104. ```
  105. And ask: *"Clone my repo in a VM, start the dev server, and screenshot the homepage in Chrome."*
  106. ## What your agent gets
  107. | Tools | |
  108. |---|---|
  109. | `vm_bash` `vm_read` `vm_write` `vm_edit` `vm_jobs` `vm_copy` | Shell, files and background jobs |
  110. | `vm_screenshot` `vm_click` `vm_type` `vm_key` `vm_scroll` `vm_browser` | Computer use and Playwright on the desktop |
  111. | `vm_manage` `vm_info` | Create, fork, snapshot, revert and remove VMs |
  112. | `vm_grant` `vm_lease` | Ask you to grant access (GitHub, ssh-agent, env vars), or lease a VM from a shared pool |
  113. You can also drive VMs yourself with the [CLI](docs/cli.md): `boxery attach demo`, `boxery desktop demo`. Less common commands are grouped in families (`boxery snapshot`, `job`, `access`, `lease`, `host`, `agent`): `boxery help` lists them, `boxery help --all` every command and older spelling.
  114. <p align="center">
  115. <img src="https://raw.githubusercontent.com/modem-dev/boxery/master/docs/computer-use.png" alt="A boxery VM's XFCE desktop: a Vite dev server and htop in terminals, a file manager, and Chrome showing the app on localhost" width="760">
  116. <br>
  117. <sub>Every VM is a full Linux desktop your agent can drive: terminals, a file manager, and a real Chrome showing the dev server it just started.</sub>
  118. </p>
  119. ## Documentation
  120. | | |
  121. |---|---|
  122. | [Install](docs/install.md) | Hosts on every backend, laptop setup, LLM providers |
  123. | [MCP server](docs/mcp.md) | stdio on your laptop, or Streamable HTTP over Tailscale |
  124. | [pi extension](docs/pi-extension.md) | `--vm`, `/vm` commands, tools, fan-out |
  125. | [CLI reference](docs/cli.md) | Every `boxery` and `boxery-host` command, and their `--json` output |
  126. | [Backends](host/backends/README.md) | libvirt, Lima, Cloud Hypervisor, exe.dev, boat.dev, OpenShell, and the backend contract |
  127. | [Grants](docs/grants.md) | Give a VM LLM providers, GitHub/HTTPS APIs (secret stays on the host), your ssh-agent, env vars, or files |
  128. | [Named hosts](docs/hosts.md) | Multiple hosts, one controller and MCP server |
  129. | [Shared pool & leases](docs/pool.md) | Several agents, one pool of VMs, no collisions |
  130. | [GitHub Actions runners](docs/github-runners.md) | Ephemeral self-hosted runners: every job in a freshly reset pool VM |
  131. | [Security model](docs/security.md) | Credential proxy, isolation, what a VM can and can't reach |
  132. | [Architecture](ARCHITECTURE.md) | Design, roadmap, and failure modes |
  133. ## Status
  134. libvirt, Lima and exe.dev are stable. The boat.dev, Cloud Hypervisor and OpenShell backends are experimental. See the [roadmap](ARCHITECTURE.md#roadmap).
  135. ## Contributing
  136. Bug reports and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
  137. ```bash
  138. npm run lint && npm test && npm run test:shell
  139. ```
  140. ## Sponsor
  141. Sponsored by [Modem](https://modem.dev?utm_source=github&utm_medium=oss&utm_campaign=oss_boxery&utm_content=readme_footer).
  142. <a href="https://modem.dev?utm_source=github&utm_medium=oss&utm_campaign=oss_boxery&utm_content=readme_footer">
  143. <picture>
  144. <source media="(prefers-color-scheme: dark)" srcset="https://modem.dev/images/logo/svg/modem-combined-white.svg">
  145. <source media="(prefers-color-scheme: light)" srcset="https://modem.dev/images/logo/svg/modem-combined-black.svg">
  146. <img src="https://modem.dev/images/logo/svg/modem-combined-black.svg" alt="Modem" width="220">
  147. </picture>
  148. </a>
  149. ## License
  150. [MIT](LICENSE) © Ben Vinegar

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.