Bumps [@boxd-sh/sdk](https://github.com/boxd-sh/sdk/tree/HEAD/typescript) from 0.2.22 to 0.3.2. <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/boxd-sh/sdk/commit/7bf5bf389a49323013fa65d222c15418b75732b6"><code>7bf5bf3</code></a> CLI 0.3.5, SDKs 0.3.2</li> <li><a href="https://github.com/boxd-sh/sdk/commit/f784e0440a26bc0c514f97cdb1ad4d1f44b2a1bf"><code>f784e04</code></a> Windows guests on self-hosted boxd: UEFI firmware boot, --os windows, license...</li> <li><a href="https://github.com/boxd-sh/sdk/commit/d037b1f6e9c58cde0cdaf31d04a9baf4a7bb0021"><code>d037b1f</code></a> Remove ListPlans, the retired monthly plan catalog</li> <li><a href="https://github.com/boxd-sh/sdk/commit/f2843553695415fcc47f89a300939d411ac9c8dc"><code>f284355</code></a> api: SetOrgBotProtectionDefault changes existing machines too</li> <li><a href="https://github.com/boxd-sh/sdk/commit/9736596397bdc10f6415348d4fd619846a51653a"><code>9736596</code></a> SDKs 0.3.1: computer use</li> <li><a href="https://github.com/boxd-sh/sdk/commit/5cdba5bb69cbfe0885d691440c9ad76c792f02cf"><code>5cdba5b</code></a> Computer use API and a settable screen size</li> <li><a href="https://github.com/boxd-sh/sdk/commit/0ee9437a651c746efd6a8f25d165c01a5b52dc51"><code>0ee9437</code></a> Show no balance for an org on a custom plan (comped), and cut long org names ...</li> <li><a href="https://github.com/boxd-sh/sdk/commit/9fc94e185819f2de28054b199e91a45efddf5f7f"><code>9fc94e1</code></a> boxd v2: storage engine, routed network and live migration</li> <li><a href="https://github.com/boxd-sh/sdk/commit/c4a3ee3d591977f4ffa36e6f573c9853839205b1"><code>c4a3ee3</code></a> billing: vCPU bills CPU time used, not the machine's size</li> <li><a href="https://github.com/boxd-sh/sdk/commit/d912ff453fdf5a13226d7c4e4f5c49bf490b3e61"><code>d912ff4</code></a> Raw TCP forwards stop refusing connections, and ExposePort answers once the p...</li> <li>See full diff in <a href="https://github.com/boxd-sh/sdk/commits/v0.3.2/typescript">compare view</a></li> </ul> </details> <br /> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
@paperclipai/plugin-boxd
boxd sandbox provider for Paperclip. boxd runs each sandbox
as an isolated KVM microVM. This package lives alongside E2B, Daytona and the
other sandbox providers, outside the root pnpm workspace. It uses the
@boxd-sh/sdk package. Paperclip's
CI release pipeline publishes this plugin to npm.
Install from npm
Once a stable release is available, install the package from the Plugins page by name, or use the CLI:
paperclipai plugin install @paperclipai/plugin-boxd
Before the first stable release, the latest tag can still point to the
0.0.0 bootstrap placeholder. That version reserves the package name and has
no plugin functionality. Check the published tags and choose a real release:
npm view @paperclipai/plugin-boxd dist-tags --json
paperclipai plugin install @paperclipai/plugin-boxd --version <published-version>
Replace <published-version> with the version shown for the desired tag, such
as canary. If no real release is available yet, use the local-path install
below. See the publishing guide for the release
and bootstrap process.
Build and install locally
Requires Node 24.11+, pnpm, and an installed Paperclip checkout.
cd packages/plugins/sandbox-providers/boxd
pnpm install --ignore-workspace --no-lockfile
pnpm typecheck
pnpm test
pnpm build
From the Paperclip checkout, with your instance running:
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts plugin install /absolute/path/to/paperclip/packages/plugins/sandbox-providers/boxd
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts plugin inspect paperclip.boxd-sandbox-provider
Configure an environment
Configure boxd under Instance Settings -> Environments, not from the
plugin page. Select the boxd provider.
apiKey: a boxd API key. Create one withboxd auth keys create paperclip --org <org>. Each key belongs to one org, and machines are created in that org. Paperclip saves a pasted key as a company secret.BOXD_API_KEYon the Paperclip host is an optional fallback when the environment has no key.reuseLease: defaultfalse. Withfalse, the plugin deletes the machine when the run ends. Withtrue, the plugin suspends the machine when the run ends, and the next run on the same issue resumes it. Disk, memory and running processes stay. The provider lease ID is the machine ID, so it stays the same across resumes.snapshot: optional snapshot name or ID. Each run restores this snapshot, for example a machine with your tools and repository already in place.vcpu: optional machine size for fresh machines: 1 vCPU/4 GB, 2/8 GB, 4/16 GB or 8/32 GB. A blank value uses the org default. A snapshot keeps its own size.org: optional org name or ID. A blank value uses the API key's org.namePrefix: machine name prefix,paperclipby default.timeoutMs: default command timeout, 3600000 ms by default.
The default boxd image is Ubuntu 24.04 with Node 24, tar, git, Docker,
Claude Code, Codex and OpenCode on the PATH. It meets
the sandbox runtime requirements without a
setup step. Use a snapshot to add other agent CLIs.
The probe creates a machine, prepares the workspace and deletes the machine. It uses real boxd resources. The probe machine also has a 15-minute boxd delete timer, and a probe whose machine could not be deleted reports a failure.
Implemented behavior
- Every machine is created with
isolated: true. An isolated machine has no metadata endpoint, no in-VMboxdCLI and no boxd integrations, and other machines in the org cannot reach it over the private network. The API key stays in the plugin worker and never enters the machine. - Machines carry the labels
paperclip-provider=boxd,paperclip-environment=<id>andpaperclip-run=<id>. Useboxd machine list --label paperclip-provider=boxdto find them. - Commands run through
shin the workspace, with quoted arguments, per-command environment, staged stdin, and separate stdout and stderr. A command timeout ends the remote process group and returnstimedOut: true. - Stdin is staged with boxd's file API in a file only the machine user can
read, and removed after the command. The workspace directory is created the
same way. A machine whose boxd agent predates the file API, such as one
restored from an older snapshot, falls back to the older upload and
mkdircalls. - A failed acquisition deletes its machine. If boxd cannot confirm the
deletion, the plugin throws
PluginEnvironmentCreationCleanupErrorwith the machine ID, so the host records it and retries the teardown. The destroy hook checks that the machine's labels match before it deletes it. - A command on a stopped machine starts the machine and runs the command one more time. A suspended or hibernated machine wakes on the command.
- Release deletes the machine and returns a receipt only after boxd no longer
lists it. With
reuseLease, release suspends the machine. A release that cancels active work stops the machine and keeps its disk. onEnvironmentStopLeasestops the machine and keeps its disk.onEnvironmentInspectLeasereads the machine state and does not change it.- When the host requests a lease expiry, the plugin sets a boxd delete timer at or before that time and returns the expiry on the lease.
- The plugin keeps one SDK client for each API key, so commands do not exchange the key for a new session token each time.
Capability boundaries
Interactive login PTYs, template capture, native file sync, persistent sessions, incremental output, duplex channels and runner ingress are not advertised. Workspace transfer uses the host's base64-over-exec fallback. boxd has one region (EU), amd64 machines only, and no GPUs.
Opt-in live tests
Default tests use a mocked SDK and do not contact boxd. To run against boxd,
export BOXD_API_KEY (and optionally BOXD_ORG), then run:
BOXD_LIVE_TEST=1 pnpm test
The live tests run every hook against boxd. They check:
- config validation, and a probe with a sized machine that deletes the machine afterwards (a bad API key returns a failed probe);
- the labels, the isolation and the org of an acquired machine;
- stdin, env, argument quoting, exit codes and stderr, and the removal of the staged stdin file;
- an empty stdin, and a staged stdin file that only the machine user can read;
- a 5 MiB round trip through the base64-over-exec path;
- that a command timeout returns
timedOutand ends the remote processes; - suspend and resume with a file and a running process kept, stop and resume with the file kept, and inspect in each state;
- a command on a stopped machine, which starts the machine and runs;
- resume and stop of a hibernated machine, stop of a suspended machine, and a
release with
cancelActiveWorkorstop_and_retain; - a release without reuse, which deletes the machine;
- a
requestedExpiresAtthat boxd enforces by deleting the machine; - a run restored from a snapshot, and a fresh machine at the configured size;
- that resume after destroy reports an expired lease, and that no test machines are left.
Each test deletes its machines in finally. The tests print timings and no
credentials. A full run takes about two minutes.
Optional managed-image inclusion
The bundled catalog key is boxd. Include the boxd directory in the Docker
CLOUD_BUNDLED_PLUGINS build argument, then include boxd in the managed
configuration's plugins.autoInstall list. The catalog entry does not
auto-install the plugin or change the default image.