The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(exe-dev): copy a source VM with exe.dev cp (#14975)
Valentin Palkovicbb73f2fe3926
diff --git a/packages/plugins/sandbox-providers/exe-dev/README.md b/packages/plugins/sandbox-providers/exe-dev/README.mdindex 52d420c25d..f1091e4896 100644--- a/packages/plugins/sandbox-providers/exe-dev/README.md+++ b/packages/plugins/sandbox-providers/exe-dev/README.md@@ -23,7 +23,7 @@ Configure exe.dev from `Instance Settings -> Environments`, not from the plugin'To use the provider successfully, the environment/host needs all of the following:-- An exe.dev API token that allows the lifecycle commands the provider uses: `new`, `ls`, and `rm`. `whoami` and `help` are recommended for manual debugging. `restart` is only needed if you extend the provider to restart retained VMs.+- An exe.dev API token that allows the lifecycle commands the provider uses: `new`, `ls`, and `rm`, plus `cp` when `sourceVm` is set. exe.dev answers 403 for a command the token does not list. `whoami` and `help` are recommended for manual debugging. `restart` is only needed if you extend the provider to restart retained VMs.- SSH access from the Paperclip host to the resulting `*.exe.xyz` VMs.- An SSH private key that exe.dev already recognizes. You can either:- paste the private key into the environment config via `sshPrivateKey`@@ -37,6 +37,7 @@ Operational notes:- Reusable leases keep the VM alive between runs. exe.dev does not expose a documented "stop and later resume" command in the public CLI docs, so `reuseLease: true` means "retain the VM" rather than "suspend it."- The provisioning path uses `https://exe.dev/exec`, which exe.dev documents as a command-style HTTPS API with a 30-second request timeout. Typical `new` calls are expected to fit inside that limit; command execution itself does not use `/exec`.- Probes still create and delete a real exe.dev VM through `/exec`, and so do the `new`/`rm` calls inside the normal acquire/release lifecycle. Treat all of those as real provisioning cost, not just probes.+- Set `sourceVm` ("Source VM" in the form) to the name of an existing exe.dev VM to copy it for each run with `exe.dev cp`, disk and config included, instead of creating a fresh VM with `exe.dev new`. This lets you prepare one VM with your toolchain and caches and start every run from it. `cp` accepts only the VM name, `cpu`, `memory`, and `disk`, so config validation rejects `sourceVm` together with `image`, `command`, `comment`, `env`, `integrations`, `tags`, `setupScript`, or `prompt`. The default setup script does not run either, so the source VM must already have Node 24.11+ and accept the configured SSH key. Do not keep secrets on the source VM: every copy inherits its disk. `cp` also goes through `/exec`, so a large disk copy must finish inside the same 30-second limit.- exe.dev runs `--setup-script` as the unprivileged `exedev` user, not as root. That user has passwordless `sudo`, so any system-level steps in a custom `setupScript` must invoke `sudo` explicitly (for example `sudo apt-get install -y …`). When you omit `setupScript`, the plugin supplies a default that installs Node 24 via the official nodesource script — Paperclip's sandbox callback bridge is a Node program, so the VM needs `node` on `PATH` before the bridge can launch.## Local developmentdiff --git a/packages/plugins/sandbox-providers/exe-dev/src/manifest.ts b/packages/plugins/sandbox-providers/exe-dev/src/manifest.tsindex bef86f3def..da176d0f96 100644--- a/packages/plugins/sandbox-providers/exe-dev/src/manifest.ts+++ b/packages/plugins/sandbox-providers/exe-dev/src/manifest.ts@@ -31,7 +31,7 @@ const manifest: PaperclipPluginManifestV1 = {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`).",+ "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",@@ -99,6 +99,14 @@ const manifest: PaperclipPluginManifestV1 = {"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`.",diff --git a/packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts b/packages/plugins/sandbox-providers/exe-dev/src/plugin.test.tsindex 16618bf507..912105db85 100644--- a/packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts+++ b/packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts@@ -106,6 +106,7 @@ describe("exe.dev sandbox provider plugin", () => {integrations: ["github"],tags: ["prod", "sandbox"],setupScript: null,+ sourceVm: null,prompt: null,timeoutMs: 450000,reuseLease: true,@@ -319,6 +320,57 @@ describe("exe.dev sandbox provider plugin", () => {});});+ it("copies the source VM with exe.dev cp instead of creating a new VM", async () => {+ fetchMock.mockResolvedValueOnce(+ new Response(JSON.stringify({+ vm_name: "paperclip-env1-run1",+ ssh_dest: "paperclip-env1-run1.exe.xyz",+ status: "running",+ }), { status: 200 }),+ );+ queueSpawnResult({ stdout: "/home/exedev\nbash\n" });+ queueSpawnResult({});++ const lease = await plugin.definition.onEnvironmentAcquireLease?.({+ driverKey: "exe-dev",+ companyId: "company-1",+ environmentId: "env-1",+ runId: "run-1",+ config: {+ apiKey: "api-key",+ sourceVm: " golden-vm ",+ image: "ubuntu:22.04",+ env: { FOO: "bar" },+ cpu: 4,+ memory: "8GB",+ disk: "40GB",+ },+ });++ expect(String(fetchMock.mock.calls[0]?.[1]?.body ?? "")).toBe(+ "cp 'golden-vm' 'paperclip-env1-run1' --json --cpu='4' --memory='8GB' --disk='40GB'",+ );+ expect(lease).toMatchObject({ providerLeaseId: "paperclip-env1-run1" });+ });++ it("rejects VM creation settings that exe.dev cp cannot apply when sourceVm is set", async () => {+ const result = await plugin.definition.onEnvironmentValidateConfig?.({+ driverKey: "exe-dev",+ config: {+ apiKey: "api-key",+ sourceVm: "golden-vm",+ image: "ubuntu:22.04",+ env: { FOO: "bar" },+ setupScript: "echo hi",+ },+ });++ expect(result?.ok).toBe(false);+ expect(result?.errors).toContain(+ "sourceVm copies an existing VM with `exe.dev cp`, which cannot apply image, env, setupScript. Clear these settings or clear sourceVm.",+ );+ });+it("uses a pasted sshPrivateKey when connecting to the VM", async () => {fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({@@ -860,6 +912,12 @@ describe("exe-dev manifest form defaults", () => {expect(properties.disk?.default).toBe("20GB");});+ it("explains the cp token permission on the Source VM field", () => {+ const sourceVm = properties.sourceVm as { title?: string; description?: string } | undefined;+ expect(sourceVm?.title).toBe("Source VM");+ expect(sourceVm?.description).toMatch(/token must allow `cp`.*403/);+ });+it("declares no default on secret-ref fields, which would be persisted as a company secret", () => {for (const prop of Object.values(properties)) {if (prop.format === "secret-ref") {diff --git a/packages/plugins/sandbox-providers/exe-dev/src/plugin.ts b/packages/plugins/sandbox-providers/exe-dev/src/plugin.tsindex a586b665f4..d45f562fc0 100644--- a/packages/plugins/sandbox-providers/exe-dev/src/plugin.ts+++ b/packages/plugins/sandbox-providers/exe-dev/src/plugin.ts@@ -24,6 +24,7 @@ interface ExeDevDriverConfig {apiKey: string | null;apiUrl: string;namePrefix: string;+ sourceVm: string | null;image: string | null;command: string | null;cpu: number | null;@@ -246,6 +247,7 @@ function parseDriverConfig(raw: Record<string, unknown>): ExeDevDriverConfig {apiKey: parseOptionalString(raw.apiKey),apiUrl: normalizeApiUrl(parseOptionalString(raw.apiUrl)),namePrefix: normalizeNamePrefix(parseOptionalString(raw.namePrefix)),+ sourceVm: parseOptionalString(raw.sourceVm),image: parseOptionalString(raw.image),command: parseOptionalString(raw.command),cpu: parseOptionalInteger(raw.cpu),@@ -313,10 +315,23 @@ function resolveSetupScript(config: ExeDevDriverConfig): string | null {return trimmed.length > 0 ? config.setupScript : null;}+function buildCopyCommand(sourceVm: string, config: ExeDevDriverConfig, vmName: string): string {+ return [+ "cp",+ shellQuote(sourceVm),+ shellQuote(vmName),+ "--json",+ ...buildFlag("cpu", config.cpu),+ ...buildFlag("memory", config.memory),+ ...buildFlag("disk", config.disk),+ ].join(" ");+}+function buildCreateCommand(config: ExeDevDriverConfig,vmName: string,): string {+ if (config.sourceVm) return buildCopyCommand(config.sourceVm, config, vmName);return ["new","--json",@@ -774,6 +789,23 @@ const plugin = definePlugin({warnings.push("The Paperclip host must have SSH access to the created exe.dev VM, and its SSH key must be registered with exe.dev. The API token only covers provisioning.",);+ if (config.sourceVm) {+ const ignored = Object.entries({+ image: config.image,+ command: config.command,+ comment: config.comment,+ env: Object.keys(config.env).length > 0,+ integrations: config.integrations.length > 0,+ tags: config.tags.length > 0,+ setupScript: config.setupScript,+ prompt: config.prompt,+ }).filter(([, value]) => value).map(([key]) => key);+ if (ignored.length > 0) {+ errors.push(+ `sourceVm copies an existing VM with \`exe.dev cp\`, which cannot apply ${ignored.join(", ")}. Clear these settings or clear sourceVm.`,+ );+ }+ }if (config.reuseLease) {warnings.push("reuseLease keeps the VM alive between runs; this provider does not suspend retained VMs.");}