0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-30 05:16:50 +01:00

Files

T

MichielMAnalyticsandClaude Opus 5.5 644937c931 feat(sandbox-providers): add boxd sandbox provider (#17284 )

<p align="center">
<img
src="https://raw.githubusercontent.com/MichielMAnalytics/paperclip/08f1cdda04443ed10fc43e7097ae0b2d14b5cc19/boxd-x-paperclip.png"
alt="boxd × Paperclip" width="700">
</p>

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent work runs in sandboxes that provider plugins supply
> - An operator selects a provider for each environment, and a reused
lease keeps one sandbox for an issue across heartbeats
> - The time to resume a reused sandbox delays every heartbeat on that
issue (see #14684)
> - boxd runs each sandbox as an isolated microVM that suspends and
resumes in milliseconds, with disk, memory and processes kept
> - This pull request adds a boxd sandbox provider plugin
> - The benefit is that operators get one more provider, with fast
resume for reused leases

## Linked Issues or Issue Description

Refs #14684. That pull request keys the remote session identity on the
provider lease ID. This provider keeps the provider lease ID equal to
the boxd machine ID, so the ID stays the same across suspend and resume.

No issue exists for boxd. The request is described below with the fields
of `adapter_request.yml`.

**Agent or provider**

boxd (https://boxd.sh). boxd runs each sandbox as a KVM microVM. The
plugin uses the public TypeScript SDK, `@boxd-sh/sdk` 0.2.20 or later.

**Why this adapter is useful**

boxd suspends a machine in about 17 ms and resumes it in about 0.2 s,
with the disk, the memory and the running processes kept. This fits
`reuseLease`: the next heartbeat on an issue continues on the same
machine. Each machine is created with `isolated: true`. An isolated
machine has no metadata endpoint, no in-VM `boxd` CLI and no boxd
integrations, so sandbox code cannot reach the provider management
interface.

**How the agent is invoked**

Build and install the plugin by local path, as the package README
describes. Open Instance Settings, then Environments. Select the `boxd`
provider and supply a boxd API key. Agents that use the environment run
their adapter commands in a boxd machine.

**Are you willing to implement it?**

Yes. This pull request is the implementation.

## What Changed

- Adds the `boxd` sandbox provider under
`packages/plugins/sandbox-providers/boxd`. Its structure follows the E2B
and exe.dev plugins. The plugin has no code comments, to follow
`CONTRIBUTING.md`.
- Implements the validate, probe, acquire, resume, release, stop,
destroy, inspect, realize-workspace and execute hooks. The manifest
declares `sandboxCapabilities: { reusableLeases: true }`.
- With `reuseLease`, release suspends the machine and resume wakes it. A
suspended, hibernated or stopped machine is woken by the matching boxd
call. A release that cancels active work stops the machine and keeps its
disk.
- Release and destroy return a `destroyed` receipt only after boxd no
longer lists the machine. Stop returns a `stopped` receipt only after
boxd reports the `stopped` state.
- When the host sets `requestedExpiresAt`, the plugin sets a boxd delete
timer at or before that time and returns `expiresAt` on the lease. The
timer is set after the create call returns, so a failure while setting
it cannot lose the machine ID.
- Commands run through `sh` with quoted arguments and per-command
environment. Stdin is staged with boxd's file API in a temporary file
that only the machine user can read, and removed afterwards; the
workspace directory is created the same way. A machine whose boxd agent
predates that API, such as one restored from an older snapshot, falls
back to the older upload and `mkdir` calls. A command timeout ends the
remote process group and returns `timedOut: true`. A command on a
stopped machine starts the machine and runs one more time.
- A failed acquisition deletes its machine. If boxd cannot confirm the
deletion, the plugin throws `PluginEnvironmentCreationCleanupError` with
the machine ID, so the host records it and retries the teardown; the
destroy hook checks the account and the machine labels before it deletes
a failed creation. A probe whose machine cannot be deleted reports a
failure, and probe machines carry a 15-minute boxd delete timer.
- The plugin keeps one SDK client for each API key. This prevents a
session token exchange for each command.
- Machines carry the labels `paperclip-provider`,
`paperclip-environment` and `paperclip-run`, so an operator can find
them with `boxd machine list --label paperclip-provider=boxd`.
- Registers the optional bundled catalog key `boxd` and the trusted
`BOXD_API_KEY` host fallback, with tests that mirror the CreateOS cases.
- Adds the package to the release manifest with `publishFromCi: false`
until a maintainer bootstraps the first npm publish.
- Adds unit tests with a mocked SDK (40 tests) and opt-in live tests
(`BOXD_LIVE_TEST=1`, 9 tests) that run every hook against boxd.
- Adds a section to `doc/plugins/PLUGIN_AUTHORING_GUIDE.md` and adds
boxd to the README provider list.

## Verification

Provider package (`packages/plugins/sandbox-providers/boxd`):

- `pnpm install --ignore-workspace --no-lockfile && pnpm typecheck`:
passes.
- `pnpm test`: 40 passed, 9 live tests skipped.
- `BOXD_LIVE_TEST=1 BOXD_API_KEY=... pnpm test`: 49 passed against
production boxd on 2026-10-28 with `@boxd-sh/sdk` 0.2.20. The live tests
cover:
- validation, and a probe at 2 vCPU that deletes its machine (a bad key
returns a failed probe);
  - the labels, the isolation and the org of an acquired machine;
- stdin, env, argument quoting, the exit code 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 (mode 600);
- a 5 MiB round trip through the base64-over-exec path (the SHA-256
matches);
- a command timeout, which returns `timedOut` and ends the remote
processes;
- suspend and resume (a file and a running process stay), stop and
resume (the file stays), 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 release with `cancelActiveWork` and with `stop_and_retain`;
  - release without reuse, which deletes the machine;
- a `requestedExpiresAt` 45 s away, which boxd enforces by deleting the
machine;
- a run restored from a snapshot, and a fresh machine at 2 vCPU / 8 GiB;
- resume after destroy, which returns an expired lease, and a final
check that no test machines remain.
- Measured times: probe 1.5 s, acquire 1.4 s, release with suspend 17
ms, resume from suspend 0.13 s, resume from hibernate 0.18 s, stop 14
ms, resume from stop 3.2 s, acquire from snapshot 1.6 s, confirmed
destroy 30 ms.
- On a machine started before boxd's file API (the test host), the
plugin's hooks fell back to the older calls: the workspace was created,
stdin was staged (mode 644, the upload path), an empty stdin worked, and
no staged file was left.

Host:

- `npx vitest run src/__tests__/bundled-plugins.test.ts
src/__tests__/plugin-database.test.ts` in `server`: 73 passed, 6 of them
new (re-run on 2026-10-28).
- `npx vitest run src/__tests__/cli-invocation-safety.test.ts` in
`server`: 40 passed. The README install commands now use the direct-exec
CLI form.
- `npx tsc --noEmit` in `server`: passes.
- `node --test scripts/release-package-map.test.mjs
scripts/check-release-package-bootstrap.test.mjs`: 18 passed.

Full stack, on a Linux host with `pnpm dev:once` in `local_trusted`
mode:

- I installed the plugin with `POST /api/plugins/install` and a local
path, then created boxd environments with a secret reference for the API
key.
- Ephemeral environment: the environment probe passed. A `claude_local`
agent (`claude-sonnet-5-5`, legacy runner) ran a task in a boxd machine.
It reported Ubuntu 24.04.5 and the workspace
`/home/boxd/paperclip-workspace`, and it marked the task done. The lease
was released and the machine was deleted.
- Reused-lease environment: the first run wrote a file and started a
background loop. After release, the machine was in the `suspended`
state. A comment with `reopen: true` started a second run. That run used
the same machine, so the provider lease ID was the same on both lease
rows. The file was there and the background loop was still running.
- Validation: a config with `vcpu: 3`, and a config with both `vcpu` and
`snapshot`, return 422 with the plugin error. The unsaved-config probe
(`/environments/probe-config`) passed in 2.0 s and deleted its machine.
A saved probe with `vcpu: 4` created a 4 vCPU / 16 GiB isolated machine.
- Cancel: cancelling the first run on a reused lease marked the lease
`expired`, and the host destroyed the machine through the plugin about
12 s later.
- Delete: deleting an environment that holds a reused lease returns 409.
With `?destroyReusableSandboxLeases=true` it returns 200, and the host
destroys the suspended machine through the plugin.
- I re-ran this flow on 2026-10-26 and again on 2026-10-28 with
`@boxd-sh/sdk` 0.2.20, from a script, with each step checked. On
2026-10-28 the ephemeral run posted its proof and both of its machines
were deleted. The reused-lease follow-up ran on the same machine (both
lease rows have the same provider lease ID), and found the file and a
background loop that had kept running. The validation errors returned
422, the unsaved-config probe passed in 1.8 s, and deleting the
environments left no machines. Every check passed except the host gap
below.
- After the runs, `boxd machine list` showed no machines with the test
prefix.

Not run: `pnpm -r typecheck`, `pnpm test:run` and `pnpm build` at the
root. The test host has no Rust toolchain for the runner binary. On that
host, `scripts/check-forbidden-tokens.mjs` adds the local username
(`boxd`) as a token. It then flags every `boxd` substring, and it also
fails on `master` there (`InboxDismissal`). A CI runner uses a different
username.

## Risks

- Host gap, not in this plugin: when a run that **resumed** a reused
lease is cancelled, the host marks the run `cancelled` but does not stop
the agent in the sandbox. The adapter keeps polling the file bridge, and
the host calls no release, stop or destroy hook. The lease stays
`active` until the environment is deleted. A plugin-side trace showed
only bridge-polling `execute` calls after the cancel. boxd is the only
provider that declares `reusableLeases`, so this path may not have been
exercised before. A cancel on the first run of a lease works as
expected.

- Low risk to existing behavior. The plugin is opt-in and is not
installed by default. The host changes add one catalog entry, one
credential passthrough entry and their tests.
- boxd machine creation has no idempotency key. If a create response is
lost, a machine can stay behind. The labels above help an operator find
it.
- A suspended machine keeps its memory image until boxd hibernates it
after a period of idle time. An operator who keeps many reused leases
pays for that storage.
- boxd stops a non-PTY command that has no output for 30 minutes. Agent
CLIs write output during a run, so this does not affect normal runs.
- boxd has one region (EU), amd64 machines only, and no GPUs. Machine
sizes are 1/4 GB, 2/8 GB, 4/16 GB and 8/32 GB.
- The new `package.json` needs code-owner approval.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) through Claude Code, with tool use
and shell execution on a boxd machine. The session does not expose the
context window size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (focused checks; the limits
are listed under Verification)
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HNWtBYxLByQmmNKjuaou1P

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-28 12:34:21 -07:00

6.9 KiB

Raw Blame History

`@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. The package is not published yet; use a local-path install. Its release manifest entry has publishFromCi: false until a maintainer bootstraps the first npm publish.

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 with boxd 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_KEY on the Paperclip host is an optional fallback when the environment has no key.
reuseLease: default false. With false, the plugin deletes the machine when the run ends. With true, 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, paperclip by 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-VM boxd CLI 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> and paperclip-run=<id>. Use boxd machine list --label paperclip-provider=boxd to find them.
Commands run through sh in the workspace, with quoted arguments, per-command environment, staged stdin, and separate stdout and stderr. A command timeout ends the remote process group and returns timedOut: 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 mkdir calls.
A failed acquisition deletes its machine. If boxd cannot confirm the deletion, the plugin throws PluginEnvironmentCreationCleanupError with 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.
onEnvironmentStopLease stops the machine and keeps its disk. onEnvironmentInspectLease reads 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 timedOut and 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 cancelActiveWork or stop_and_retain;
a release without reuse, which deletes the machine;
a requestedExpiresAt that 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.

6.9 KiB Raw Blame History

@paperclipai/plugin-boxd