Skip to main content
Paperclip's banner, colored bars over the line A team of agents for every person, inside the boxd card. Paperclip is the open-source app people use to manage AI agents at work. Every agent run works in a sandbox environment, and Paperclip supports several providers for it. The boxd sandbox provider gives each run its own boxd machine, a hardware-isolated Linux VM that already has Claude Code, Codex, OpenCode, Node 24, git, and Docker, so it meets Paperclip’s sandbox requirements without a setup step. With lease reuse on, a machine is suspended when its run ends, and the next run on the same issue resumes it with its disk, memory, and running processes.

​
Set up

The plugin is merged into Paperclip but not yet published to npm, so install it from a Paperclip checkout.
1

Create an API key

Machines are created and billed in the key’s organization.
2

Build the plugin

From the Paperclip checkout, with Node 24.11 or later and pnpm:
3

Install it into your Paperclip instance

With your instance running, from the root of the checkout:
4

Add a boxd environment

In Instance Settings → Environments, add an environment, select the boxd provider, and paste the API key. Paperclip saves it as a company secret, and falls back to BOXD_API_KEY on the Paperclip host when an environment has no key.
Paperclip checks a new environment by creating a machine, preparing its workspace, and deleting it again. That probe machine also gets a 15-minute delete timer, so it can’t outlive a failed check.

​
Keep a machine between runs

By default the plugin deletes a run’s machine when the run ends. Set reuseLease to true and it suspends the machine instead: the next run on the same issue resumes it with its files, memory, and running processes where they were. In the plugin’s live tests, resuming took about 0.13 seconds. To start every run from a prepared machine, with your tools and repository already in place, set snapshot to the name or id of a snapshot.

​
What each machine gets

  • Isolation: every machine is created isolated, with no metadata endpoint, no in-machine boxd CLI or account integrations, and no route to your organization’s other machines. The API key stays in the plugin worker and never enters the machine.
  • A size: vcpu picks one of boxd’s machine sizes, 1, 2, 4, or 8 vCPUs with 4 GiB each. Left blank, it uses your organization’s default. A machine from a snapshot keeps the size it was saved at.
  • Labels: each machine carries paperclip-provider=boxd and the ids of its environment and run, so boxd machine list --label paperclip-provider=boxd finds them.
  • A deadline: when Paperclip sets a lease expiry, the plugin sets the machine’s delete-after timer at or before it.
  • Cleanup: a finished run deletes its machine, and a failed start deletes the machine it made. If boxd can’t confirm a deletion, Paperclip records the machine and tries again.
The plugin’s README has the full configuration reference and the opt-in live tests.