mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The exe.dev sandbox provider plugin gives each run its own exe.dev VM > - Today the plugin always creates that VM with `exe.dev new`, so every run starts from a bare image > - Large repositories need a long setup on each VM: toolchain, agent CLIs, package caches, and browsers for tests > - exe.dev has a `cp` command that copies an existing VM, disk and config included > - This pull request adds an optional `sourceVm` setting. When it is set, the plugin copies that VM with `exe.dev cp` instead of creating a new one > - The benefit is that operators prepare one VM once, and each run starts from it ## Linked Issues or Issue Description Refs #13575. That open PR rewrites this plugin for durable exe.dev environments. It does not add `cp`. The two changes touch the same files and can conflict. I found no issue for this. Feature description: **Subsystem affected** packages/plugins: the exe.dev sandbox provider plugin (`packages/plugins/sandbox-providers/exe-dev`). **Problem or motivation** Each run gets a fresh exe.dev VM from `exe.dev new`. We use a large monorepo (Storybook). Before the agent can work, each run must install Node, the agent CLIs, and Playwright browsers. Each run must also fill the package manager cache. This setup takes a long time on each run. **Proposed solution** Add a `sourceVm` setting ("Source VM" in the environment form). When it is set, lease acquisition and probes run `exe.dev cp <sourceVm> <generated-name> --json`. The command also sends the configured `cpu`, `memory`, and `disk`. The VM name, the SSH setup, the workspace, and the release and destroy steps do not change. When the setting is blank, the plugin uses `exe.dev new` as before. **Alternatives considered** - A custom image with `--image`: the operator must build and push a large image for each change. A private registry needs `--registry-auth`, and the plugin does not support it. - `--setup-script`: it runs on every new VM, so each run still pays the setup cost. It also has a 10 KiB limit. - `reuseLease`: it keeps one VM for one lease. It does not give each run a fresh copy of a prepared VM. **Roadmap alignment** The change stays inside an existing sandbox provider plugin. `ROADMAP.md` lists "Cloud / Sandbox agent support" as done and does not plan VM copies. CONTRIBUTING.md asks to discuss features in Discord `#dev` first. I open this pull request as a draft and start that discussion in `#dev`. **Additional context** exe.dev documents `cp` here: https://exe.dev/docs/cli-cp. exe.dev token permissions are documented here: https://exe.dev/docs/https-api. ## What Changed - `plugin.ts`: add `sourceVm` to the driver config. - `plugin.ts`: `buildCreateCommand` sends `cp` when `sourceVm` is set. - `plugin.ts`: config validation rejects `sourceVm` together with settings that `cp` cannot apply (`image`, `command`, `comment`, `env`, `integrations`, `tags`, `setupScript`, `prompt`). The error names the settings to clear. The server shows validation errors in the form, but it does not show warnings after a successful save. - `manifest.ts`: add the "Source VM" field to the "VM creation" group. Its description says that the API token must allow `cp`, because exe.dev returns 403 for a command that the token does not list. The API key description now also mentions `cp`. - `README.md`: document `sourceVm`, its limits, and the token permission. - `plugin.test.ts`: add tests for the `cp` command, the validation error, and the form field. Add `sourceVm: null` to the expected normalized config. ## Verification - `vitest run --config vitest.config.ts` in `packages/plugins/sandbox-providers/exe-dev`: 38 tests pass. The three new tests fail without the change. - `tsc --noEmit -p packages/plugins/sandbox-providers/exe-dev`: no errors. - Manual test on a self-hosted Paperclip instance (2026.1001.0). I applied the same change to the installed plugin. I prepared a source VM and set "Source VM" on an exe.dev environment. Then I ran agent tasks. Each run copied the source VM and ran in the copy. Paperclip deleted the copy at release. - With an API token that does not list `cp`, the run fails with `exe.dev API command failed (403) for: cp '<source>' '<name>' --json ...`. The new field description tells operators about this. ## Risks - Low risk. The new code runs only when `sourceVm` is set. The `new` path is unchanged. - `cp` uses the same `/exec` endpoint and its 30-second request limit. A copy of a very large disk can take longer than the limit. - Every copy inherits the source VM disk. The README tells operators not to keep secrets on the source VM. - Can conflict with #13575. ## Model Used - Provider and model: Anthropic Claude Opus 5.5. - Model ID: `claude-opus-5-5`. - Tool: Claude Code, with tool use (shell commands and file edits) and extended thinking. - Context window: the tool does not report it. - The model wrote the change and the tests. A human tested the feature on a real exe.dev setup. ## 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 - [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) <img width="1166" height="852" alt="Bildschirmfoto 2026-10-02 um 23 04 32" src="https://github.com/user-attachments/assets/c057bee4-9f27-4a69-945e-0f71d5bcc1ba" /> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
192 lines
7.4 KiB
TypeScript
192 lines
7.4 KiB
TypeScript
import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
|
|
|
|
const PLUGIN_ID = "paperclip.exe-dev-sandbox-provider";
|
|
const PLUGIN_VERSION = "0.1.2";
|
|
|
|
const manifest: PaperclipPluginManifestV1 = {
|
|
id: PLUGIN_ID,
|
|
apiVersion: 1,
|
|
version: PLUGIN_VERSION,
|
|
displayName: "exe.dev Sandbox Provider",
|
|
description:
|
|
"Sandbox provider plugin that provisions exe.dev VMs as Paperclip execution environments.",
|
|
author: "Paperclip",
|
|
categories: ["automation"],
|
|
capabilities: ["environment.drivers.register"],
|
|
entrypoints: {
|
|
worker: "./dist/worker.js",
|
|
},
|
|
environmentDrivers: [
|
|
{
|
|
driverKey: "exe-dev",
|
|
kind: "sandbox_provider",
|
|
displayName: "exe.dev VM",
|
|
description:
|
|
"Provisions exe.dev VMs through the HTTPS API, then runs commands over direct SSH for long-lived Paperclip workloads.",
|
|
configSchema: {
|
|
type: "object",
|
|
properties: {
|
|
// ---- Essentials (always visible, in this order) ----
|
|
apiKey: {
|
|
type: "string",
|
|
format: "secret-ref",
|
|
description:
|
|
"Paste your exe.dev API token, or pick a saved Paperclip secret. Create one at exe.dev → Settings → API tokens with `/exec` scope (`new`, `ls`, `rm`, plus `cp` if you use Source VM).",
|
|
},
|
|
sshPrivateKey: {
|
|
type: "string",
|
|
format: "secret-ref",
|
|
maxLength: 8192,
|
|
description:
|
|
"Paste the SSH private key you registered with exe.dev, or pick a saved secret. Leave blank to fall back to an on-host key (see Advanced → SSH access).",
|
|
},
|
|
// ---- Advanced: SSH access ----
|
|
sshUser: {
|
|
type: "string",
|
|
description:
|
|
"Login user on the VM. Leave blank to use the image default, usually `root`.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "SSH access",
|
|
},
|
|
sshIdentityFile: {
|
|
type: "string",
|
|
description:
|
|
"Absolute path to a private key on the Paperclip host. Used only when SSH Private Key is empty.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "SSH access",
|
|
},
|
|
sshPort: {
|
|
type: "number",
|
|
description: "SSH port for direct VM access.",
|
|
default: 22,
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "SSH access",
|
|
},
|
|
strictHostKeyChecking: {
|
|
type: "string",
|
|
description:
|
|
"Host key policy passed to ssh via StrictHostKeyChecking. Typical values are `accept-new`, `yes`, or `no`.",
|
|
default: "accept-new",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "SSH access",
|
|
},
|
|
// ---- Advanced: VM resources ----
|
|
image: {
|
|
type: "string",
|
|
description: "Optional container image to use when creating the VM.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM resources",
|
|
},
|
|
cpu: {
|
|
type: "number",
|
|
description: "Optional CPU count passed to `exe.dev new --cpu`.",
|
|
default: 4,
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM resources",
|
|
},
|
|
memory: {
|
|
type: "string",
|
|
description: "Optional memory size such as `4GB`.",
|
|
default: "4GB",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM resources",
|
|
},
|
|
disk: {
|
|
type: "string",
|
|
description: "Optional disk size such as `20GB`.",
|
|
default: "20GB",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM resources",
|
|
},
|
|
// ---- Advanced: VM creation ----
|
|
sourceVm: {
|
|
type: "string",
|
|
title: "Source VM",
|
|
description:
|
|
"Name of an existing exe.dev VM to copy for each run with `exe.dev cp`, disk and config included. Leave blank to create a fresh VM with `exe.dev new`. Your API token must allow `cp`: tokens list their permitted commands, and one without `cp` fails with a 403. When set, leave image, command, env, integrations, tags, setup script, prompt, and comment empty: `cp` cannot apply them, and saving fails until they are cleared.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
command: {
|
|
type: "string",
|
|
description: "Optional container command passed to `exe.dev new --command`.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
env: {
|
|
type: "object",
|
|
description: "Optional environment variables applied at VM creation time.",
|
|
additionalProperties: { type: "string" },
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
integrations: {
|
|
type: "array",
|
|
description: "Optional exe.dev integrations to attach during VM creation.",
|
|
items: { type: "string" },
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
tags: {
|
|
type: "array",
|
|
description: "Optional tags to apply during VM creation.",
|
|
items: { type: "string" },
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
setupScript: {
|
|
type: "string",
|
|
description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
prompt: {
|
|
type: "string",
|
|
description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
comment: {
|
|
type: "string",
|
|
description: "Optional short note attached to created VMs.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
namePrefix: {
|
|
type: "string",
|
|
description: "Optional prefix used when generating VM names.",
|
|
default: "paperclip",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "VM creation",
|
|
},
|
|
// ---- Advanced: API + runtime ----
|
|
apiUrl: {
|
|
type: "string",
|
|
description:
|
|
"Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "API + runtime",
|
|
},
|
|
timeoutMs: {
|
|
type: "number",
|
|
description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
|
|
default: 300000,
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "API + runtime",
|
|
},
|
|
reuseLease: {
|
|
type: "boolean",
|
|
description:
|
|
"Whether to keep the VM alive between runs instead of deleting it on release.",
|
|
default: false,
|
|
"x-paperclip-advanced": true,
|
|
"x-paperclip-group": "API + runtime",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
],
|
|
};
|
|
|
|
export default manifest;
|