Skip to content

The open-source app everyone uses to manage agents at work

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.md
index 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 development
diff --git a/packages/plugins/sandbox-providers/exe-dev/src/manifest.ts b/packages/plugins/sandbox-providers/exe-dev/src/manifest.ts
index 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.ts
index 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.ts
index 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.");
}