> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Paperclip

> Run each Paperclip agent run on its own isolated boxd machine, and resume it later with its disk, memory, and processes.

![Paperclip's banner, colored bars over the line A team of agents for every person, inside the boxd card.](https://mintcdn.com/azin/6pxNMFBT7Eg7ouNq/images/boxd-x-paperclip.jpg?fit=max\&auto=format\&n=6pxNMFBT7Eg7ouNq\&q=85\&s=169fcb78e6403ac4be9c6fcf8991a39a)

[Paperclip](https://paperclip.ing) 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](https://github.com/paperclipai/paperclip/pull/17284) 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**

```bash theme={"theme":"github-dark"}
boxd auth keys create paperclip --org <your-org>
```

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:

```bash theme={"theme":"github-dark"}
cd packages/plugins/sandbox-providers/boxd
pnpm install --ignore-workspace --no-lockfile
pnpm build
```

**3. Install it into your Paperclip instance**

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

```bash theme={"theme":"github-dark"}
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts plugin install /absolute/path/to/paperclip/packages/plugins/sandbox-providers/boxd
```

**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](https://docs.boxd.sh/guides/snapshots.md).

## 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](https://docs.boxd.sh/guides/machine-specs.md), 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](https://docs.boxd.sh/guides/delete-after.md) 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](https://github.com/paperclipai/paperclip/blob/master/packages/plugins/sandbox-providers/boxd/README.md) has the full configuration reference and the opt-in live tests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.