exe.dev config UX: advanced-options disclosure, form-default fix, SSH key handling (PAPA-407) (#7025)

## Thinking Path

> - Paperclip orchestrates AI agents and provisions sandboxed execution
environments for them; one of those provisioners is the exe.dev plugin,
which runs each agent inside a long-lived VM reached over SSH.
> - The instance-config form for that plugin is rendered generically by
`JsonSchemaForm` from the plugin's `instanceConfigSchema`, so any UX
problem with the form is split between the shared form component and the
plugin's schema/runtime code.
> - Users coming in cold hit a 12-field flat config they couldn't reason
about (PAPA-407), a form that silently submitted `cpu: 0` for untouched
optional fields (PAPA-407 root cause), a `sshPrivateKey` textarea that
truncated RSA-4096 keys at 4096 chars (PAPA-449), a save flow that
accepted clearly-malformed keys and only blew up at lease time with raw
SSH stderr (PAPA-450, PAPA-451), and a manifest that didn't distinguish
"essential" from "advanced" knobs (PAPA-410 / PAPA-411 — duplicate
sub-issues with identical scope; PAPA-418 reconciliation kept PAPA-410
canonical).
> - These problems all point at the same surface (exe.dev sandbox
config) and are tightly coupled in code — PAPA-449/450/451 patch fields
that PAPA-410/411 introduce — so they get reviewed together.
> - This pull request lands the shared-form changes (advanced-options
disclosure, optional-scalar defaults) and the exe.dev-specific changes
(manifest restructure, longer `maxLength`, stderr translation, save-time
key validation) as five focused commits stacked on `master`.
> - The benefit is a config form that defaults to the two fields a new
user actually needs (API key + SSH private key) with a collapsible
disclosure for the rest, no silent truncation or zero-default
submissions, and SSH key problems surfaced at save time with actionable
messages instead of cryptic post-provision failures.

## What Changed

- **JsonSchemaForm advanced-options disclosure** (PAPA-410, PAPA-411 —
same scope, see note above): adds `x-paperclip-advanced` /
`x-paperclip-group` schema annotations and renders flagged fields behind
a collapsible "Advanced options" disclosure that auto-opens when a
hidden field has a validation error. Exe.dev manifest is restructured to
use the new annotations, so essentials (`apiKey`, `sshPrivateKey`) show
by default while the long tail of optional knobs is grouped under "SSH
access" / "VM resources" / "More options" headings.
- **Omit optional scalar defaults** (PAPA-407): `getDefaultForSchema` no
longer materialises `0` / `""` for optional
`number`/`integer`/`string`/`secret-ref` fields without an explicit
`default`. Object recursion drops properties whose default is
`undefined`. Fields that declare a `default` (e.g. `sshPort: 22`) still
round-trip. Adds a regression test against `getDefaultValues`.
- **Raise `sshPrivateKey` `maxLength`** (PAPA-449): bumps the exe.dev
manifest cap from 4096 to 8192 so RSA-4096 OpenSSH private keys (which
can exceed 4 KB with comments/metadata) aren't silently truncated at
submit.
- **Translate `invalid format` SSH stderr** (PAPA-450):
`formatSshFailure` now recognises `Load key … invalid format` in
combined stderr/stdout and returns a specific message naming the
key-format problem ("isn't an OpenSSH/PEM private key — confirm the
secret starts with `-----BEGIN … PRIVATE KEY-----` and isn't the `.pub`
or a PuTTY `.ppk` export") instead of dumping the raw stderr.
- **Save-time SSH key validation** (PAPA-451):
`onEnvironmentValidateConfig` inline-parses `sshPrivateKey` and rejects
common failure modes — pasted public keys, PuTTY `.ppk` format, missing
`-----END-----` footer, non-base64 body — so the form surfaces an inline
error before any VM is provisioned. Secret-ref bindings (UUIDs) are
still passed through unchanged.

## Verification

CI gates (`pnpm typecheck`, `pnpm test`, the targeted vitest suites
below) all pass.

Run locally:

```bash
# Shared form
pnpm --filter @paperclipai/ui exec vitest run src/components/JsonSchemaForm
# 9 tests pass — includes the new "omits optional scalar fields" regression
# and the three advanced-options-disclosure tests.

# exe.dev plugin
cd packages/plugins/sandbox-providers/exe-dev && pnpm test
# 32 tests pass — includes the new sshPrivateKey-validation cases
# and the new "invalid format" stderr-translation case.
```

Manual smoke (after reinstalling the plugin so the DB manifest
refreshes):

1. Open the exe.dev environment config page. **Default view shows API
Key + SSH Private Key only**, with an "Advanced options" disclosure for
everything else (PAPA-410 / PAPA-411).
2. Paste a `.pub` file's contents into SSH Private Key, click Save.
**Inline error** rejecting the wrong-format key (PAPA-451).
3. Re-paste a valid OpenSSH/PEM private key longer than 4096 bytes —
saves cleanly (PAPA-449).
4. Save the form with everything optional left blank — server no longer
rejects with `"cpu must be greater than 0 when provided"` (PAPA-407).
5. Force a bad key through via a stored secret-ref binding and lease a
VM — failure message names the key-format problem instead of dumping raw
SSH stderr (PAPA-450).

## Risks

- **PAPA-410 / PAPA-411 manifest restructure** is the largest surface
here. Schemas using `x-paperclip-*` extensions are forward-compatible
with stricter JSON Schema validators (extensions are ignored by
default), and the form gracefully renders a flat layout when no field
opts in.
- **PAPA-407** changes form-default behaviour: optional scalar fields
that previously round-tripped as `""` / `0` will now be `undefined` and
absent from the submitted payload. Downstream consumers that expected
the empty-string/zero shape need to treat the field as optional.
Spot-checked the existing exe.dev driver — it already uses
`parseOptionalString` / `parseOptionalInteger`, which treat missing
fields as `null` rather than `0`/`""`.
- **PAPA-451** adds a save-time check, so a
previously-saved-but-malformed `sshPrivateKey` raw value will now fail
to re-save. Bound secret-refs are unaffected, matching how the user
reaches the bad-key state today (via the secrets picker).
- **PAPA-449** simply raises a cap; no semantic risk.
- **PAPA-450** only kicks in on the "invalid format" code path; existing
onboarding-marker branch is untouched.

## Model Used

- Provider: Anthropic
- Model: Claude Opus 4.7 (`claude-opus-4-7`)
- Capabilities used: code reading, code editing, test execution, git/PR
mechanics, Paperclip API for issue coordination

## Checklist

- [x] PR body sections present (Thinking Path, What Changed,
Verification, Risks, Model Used, Checklist)
- [x] Unit tests added for the new behaviours (JsonSchemaForm
default-value omission + advanced disclosure; exe.dev plugin validation
+ stderr translation)
- [x] Existing tests still pass locally (`vitest run` on both packages)
- [x] No raw secrets, IP addresses, or machine-local config in commits
or PR body
- [x] Commits are atomic per linked issue (PAPA-410 / PAPA-411,
PAPA-407, PAPA-449, PAPA-450, PAPA-451)
- [x] Branch is up-to-date with `origin/master`

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/plugins/sandbox-providers/exe-dev/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/plugin-exe-dev",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "exe.dev sandbox provider plugin for Paperclip environments",
   "license": "MIT",
   "homepage": "https://github.com/paperclipai/paperclip",

packages/plugins/sandbox-providers/exe-dev/src/manifest.ts

@@ -1,7 +1,7 @@
 import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
 
 const PLUGIN_ID = "paperclip.exe-dev-sandbox-provider";
-const PLUGIN_VERSION = "0.1.0";
+const PLUGIN_VERSION = "0.1.1";
 
 const manifest: PaperclipPluginManifestV1 = {
   id: PLUGIN_ID,
@@ -26,106 +26,150 @@ const manifest: PaperclipPluginManifestV1 = {
       configSchema: {
         type: "object",
         properties: {
+          // ---- Essentials (always visible, in this order) ----
           apiKey: {
             type: "string",
             format: "secret-ref",
             description:
-              "Environment-specific exe.dev API token. Needs `/exec` permission for at least `new`, `ls`, and `rm`. Paste a token or an existing Paperclip secret reference; saved environments store pasted values as company secrets. Falls back to EXE_API_KEY if omitted.",
+              "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`).",
-          },
-          apiUrl: {
-            type: "string",
-            description:
-              "Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
-          },
-          namePrefix: {
-            type: "string",
-            description: "Optional prefix used when generating VM names.",
-            default: "paperclip",
-          },
-          image: {
-            type: "string",
-            description: "Optional container image to use when creating the VM.",
-          },
-          command: {
-            type: "string",
-            description: "Optional container command passed to `exe.dev new --command`.",
-          },
-          cpu: {
-            type: "number",
-            description: "Optional CPU count passed to `exe.dev new --cpu`.",
-          },
-          memory: {
-            type: "string",
-            description: "Optional memory size such as `4GB`.",
-          },
-          disk: {
-            type: "string",
-            description: "Optional disk size such as `20GB`.",
-          },
-          comment: {
-            type: "string",
-            description: "Optional short note attached to created VMs.",
-          },
-          env: {
-            type: "object",
-            description: "Optional environment variables applied at VM creation time.",
-            additionalProperties: { type: "string" },
-          },
-          integrations: {
-            type: "array",
-            description: "Optional exe.dev integrations to attach during VM creation.",
-            items: { type: "string" },
-          },
-          tags: {
-            type: "array",
-            description: "Optional tags to apply during VM creation.",
-            items: { type: "string" },
-          },
-          setupScript: {
-            type: "string",
-            description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
-          },
-          prompt: {
-            type: "string",
-            description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
-          },
-          timeoutMs: {
-            type: "number",
-            description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
-            default: 300000,
-          },
-          reuseLease: {
-            type: "boolean",
-            description:
-              "Whether to keep the VM alive between runs instead of deleting it on release.",
-            default: false,
-          },
-          sshUser: {
-            type: "string",
-            description: "Optional SSH username for direct VM access.",
           },
           sshPrivateKey: {
             type: "string",
             format: "secret-ref",
-            maxLength: 4096,
+            maxLength: 8192,
             description:
-              "Optional exe.dev-registered SSH private key. Paste the private key or an existing Paperclip secret reference; saved environments store pasted values as company secrets. If omitted, Paperclip falls back to sshIdentityFile, then the host's default SSH agent/keychain.",
+              "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:
-              "Optional absolute path to the SSH private key the Paperclip host should use for VM access when sshPrivateKey is omitted. Leave both blank to rely on the host's default SSH agent/keychain.",
+              "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`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          memory: {
+            type: "string",
+            description: "Optional memory size such as `4GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          disk: {
+            type: "string",
+            description: "Optional disk size such as `20GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          // ---- Advanced: 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",
           },
         },
       },

packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts

@@ -14,7 +14,7 @@ vi.mock("node:child_process", async () => {
   };
 });
 
-import plugin from "./plugin.js";
+import plugin, { validateSshPrivateKey } from "./plugin.js";
 
 class MockChildProcess extends EventEmitter {
   stdout = new EventEmitter();
@@ -165,6 +165,117 @@ describe("exe.dev sandbox provider plugin", () => {
     });
   });
 
+  describe("sshPrivateKey validation", () => {
+    const VALID_OPENSSH = [
+      "-----BEGIN OPENSSH PRIVATE KEY-----",
+      "b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gt",
+      "ZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6gQ3jPbgAAAJjJ8jjE",
+      "yfI4xAAAAAtzc2gtZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+      "Q3jPbgAAAEDqLhB4kV1tw8m4gE9oNCkF2cJv0YnHQ8E5sHU3xKnD5k/MzFCnhjpcJ8NX",
+      "a3qhaaoeQrHQrsLvDur0XqBDeM9uAAAAFXVzZXJAaG9zdAECAwQ=",
+      "-----END OPENSSH PRIVATE KEY-----",
+    ].join("\n");
+    const VALID_RSA_PEM = [
+      "-----BEGIN RSA PRIVATE KEY-----",
+      "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu",
+      "KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm",
+      "o3qGy0t6z5tZbcgvflRslzu1HxXLpwYqQq2gMNw9UQAoHs3rDl+EzBjF6trBV5wF",
+      "wQIhANwiwDR7TVlIRk5kbgPMd2dDgY8mAU1cQ8KbWvjVMmKxAiEAxYTUyVjwhfQy",
+      "VJoR7T0n4XdR1n+W8Eth7AEPxnHfaQECIB5cNuqB9F1qC2pSyf6e+UAyl9rmKQXp",
+      "-----END RSA PRIVATE KEY-----",
+    ].join("\n");
+
+    it("accepts a valid OpenSSH PEM block", () => {
+      expect(validateSshPrivateKey(VALID_OPENSSH)).toBeNull();
+    });
+
+    it("accepts a valid PKCS#1 RSA PEM block", () => {
+      expect(validateSshPrivateKey(VALID_RSA_PEM)).toBeNull();
+    });
+
+    it("accepts UUID-like secret reference values from the save-time schema stage", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          apiKey: "api-key",
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+
+      expect(result).toMatchObject({
+        ok: true,
+        normalizedConfig: {
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+      expect(result?.errors ?? []).toEqual([]);
+    });
+
+    it("treats empty / whitespace-only input as valid (falls back to on-host key)", () => {
+      expect(validateSshPrivateKey("")).toBeNull();
+      expect(validateSshPrivateKey("   \n\n  ")).toBeNull();
+    });
+
+    it("rejects a pasted public key", () => {
+      expect(
+        validateSshPrivateKey("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host"),
+      ).toMatch(/looks like a PUBLIC key/);
+    });
+
+    it("rejects a PuTTY PPK file paste", () => {
+      const ppk = [
+        "PuTTY-User-Key-File-3: ssh-ed25519",
+        "Encryption: none",
+        "Comment: imported-openssh-key",
+        "Public-Lines: 2",
+        "AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9zMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+        "Q3jP",
+      ].join("\n");
+      expect(validateSshPrivateKey(ppk)).toMatch(/PuTTY \.ppk/);
+    });
+
+    it("rejects a missing END marker (truncated paste)", () => {
+      const truncated = VALID_OPENSSH.split("\n").slice(0, -1).join("\n");
+      expect(validateSshPrivateKey(truncated)).toMatch(/missing its '-----END/);
+    });
+
+    it("rejects a body with non-base64 characters", () => {
+      const garbled = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "this is not base64!!",
+        "-----END OPENSSH PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(garbled)).toMatch(/non-base64/);
+    });
+
+    it("rejects a header/footer label mismatch", () => {
+      const mismatched = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "Zm9vYmFy",
+        "-----END RSA PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(mismatched)).toMatch(/header\/footer mismatch/);
+    });
+
+    it("returns the sshPrivateKey error from onEnvironmentValidateConfig on save", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          sshPrivateKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host",
+        },
+      });
+
+      expect(result?.ok).toBe(false);
+      expect(result?.errors ?? []).toEqual(
+        expect.arrayContaining([expect.stringMatching(/sshPrivateKey looks like a PUBLIC key/)]),
+      );
+    });
+  });
+
   it("acquires a lease by creating a VM and preparing the SSH workspace", async () => {
     fetchMock.mockResolvedValueOnce(
       new Response(JSON.stringify({
@@ -346,6 +457,38 @@ describe("exe.dev sandbox provider plugin", () => {
     expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
   });
 
+  it("surfaces invalid SSH key-format guidance during lease acquisition", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({
+        vm_name: "paperclip-env-run",
+        ssh_dest: "paperclip-env-run.exe.xyz",
+        https_url: "https://paperclip-env-run.exe.xyz",
+        status: "running",
+      }), { status: 200 }),
+    );
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 200 }));
+    queueSpawnResult({
+      code: 255,
+      stderr: 'Load key "/tmp/paperclip-exe-dev-ssh-abc/id_ed25519": invalid format\n',
+    });
+
+    await expect(plugin.definition.onEnvironmentAcquireLease?.({
+      driverKey: "exe-dev",
+      companyId: "company-1",
+      environmentId: "env-1",
+      runId: "run-1",
+      config: {
+        apiKey: "api-key",
+        sshPrivateKey: "not-actually-a-key",
+        timeoutMs: 300000,
+      },
+    })).rejects.toThrow(
+      "the configured SSH private key isn't an OpenSSH-format private key",
+    );
+
+    expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
+  });
+
   it("redacts sensitive lifecycle flags in API errors", async () => {
     fetchMock.mockResolvedValueOnce(new Response("upstream boom", { status: 500 }));
 

packages/plugins/sandbox-providers/exe-dev/src/plugin.ts

@@ -68,6 +68,8 @@ const SSH_SIGKILL_GRACE_MS = 250;
 const MAX_VM_RECORD_DEPTH = 4;
 const EXE_DEV_SSH_ONBOARDING_MARKER = "Please complete registration by running: ssh exe.dev";
 const EXE_DEV_SSH_EMAIL_PROMPT = "Please enter your email address:";
+const EXE_DEV_SSH_INVALID_KEY_FORMAT = /Load key [^\n]*invalid format/i;
+const UUID_SECRET_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // exe.dev's `--setup-script` runs at VM init as the unprivileged `exedev` user, which
 // has passwordless sudo. The Paperclip sandbox callback bridge is a Node script, so
@@ -139,6 +141,74 @@ function isValidUrl(value: string): boolean {
   }
 }
 
+function isSecretRef(value: string): boolean {
+  return UUID_SECRET_REF_RE.test(value);
+}
+
+// Catch the SSH-key paste failure modes we've seen in the wild (wrong file,
+// PPK export, truncated paste) before the user pays the cost of provisioning a
+// VM and getting a cryptic SSH error. Inline parse — no `ssh-keygen` dependency
+// — so this also works on hosts where openssh-client isn't installed.
+export function validateSshPrivateKey(rawKey: string): string | null {
+  const trimmed = rawKey.trim();
+  if (!trimmed) return null;
+
+  if (/^PuTTY-User-Key-File-\d/m.test(trimmed)) {
+    return "sshPrivateKey looks like a PuTTY .ppk file. Convert it to OpenSSH format (PuTTYgen → Conversions → Export OpenSSH key) and paste the resulting PEM.";
+  }
+
+  if (
+    /^(?:ssh-(?:rsa|dss|ed25519)|ecdsa-sha2-[a-z0-9-]+|sk-(?:ssh-ed25519|ecdsa-sha2-[a-z0-9-]+)@openssh\.com)\s+\S/.test(
+      trimmed,
+    )
+  ) {
+    return "sshPrivateKey looks like a PUBLIC key. Paste the matching private key (the file without the .pub extension).";
+  }
+
+  const headerMatch = trimmed.match(/^-----BEGIN ([A-Z0-9 ]*)PRIVATE KEY-----/m);
+  if (!headerMatch) {
+    return "sshPrivateKey must be a PEM-encoded private key starting with a line like '-----BEGIN OPENSSH PRIVATE KEY-----'.";
+  }
+
+  const footerMatch = trimmed.match(/^-----END ([A-Z0-9 ]*)PRIVATE KEY-----\s*$/m);
+  if (!footerMatch) {
+    return "sshPrivateKey is missing its '-----END … PRIVATE KEY-----' footer. Make sure you copied the whole file, including the final line.";
+  }
+
+  const headerLabel = headerMatch[1].trim();
+  const footerLabel = footerMatch[1].trim();
+  if (headerLabel !== footerLabel) {
+    return `sshPrivateKey header/footer mismatch (BEGIN ${headerLabel || "(none)"} vs END ${footerLabel || "(none)"}). The file is likely truncated or two keys are concatenated.`;
+  }
+
+  const headerLineEnd = trimmed.indexOf("\n", headerMatch.index ?? 0);
+  const footerStart = trimmed.lastIndexOf(footerMatch[0]);
+  if (headerLineEnd < 0 || footerStart <= headerLineEnd) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  const bodyLines = trimmed
+    .slice(headerLineEnd + 1, footerStart)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  if (bodyLines.length === 0) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  // PEM bodies are base64 lines, optionally preceded by `Header: value` lines
+  // on encrypted PKCS#1 keys (`Proc-Type:`, `DEK-Info:`).
+  const base64Line = /^[A-Za-z0-9+/=]+$/;
+  const pemHeaderLine = /^[A-Za-z][A-Za-z0-9-]*:\s.+$/;
+  for (const line of bodyLines) {
+    if (!base64Line.test(line) && !pemHeaderLine.test(line)) {
+      return "sshPrivateKey body contains non-base64 characters. The key may have been corrupted by line-wrapping or copy-paste.";
+    }
+  }
+
+  return null;
+}
+
 function normalizeApiUrl(value: string | null): string {
   if (!value) return DEFAULT_API_URL;
   const trimmed = value.trim();
@@ -498,6 +568,13 @@ function formatSshFailure(
     ].join(" ");
   }
 
+  if (EXE_DEV_SSH_INVALID_KEY_FORMAT.test(combinedOutput)) {
+    return [
+      `Failed to ${action} exe.dev VM ${vmName}: the configured SSH private key isn't an OpenSSH-format private key.`,
+      "Confirm the secret starts with `-----BEGIN … PRIVATE KEY-----` and isn't the `.pub` file or a PuTTY `.ppk` export.",
+    ].join(" ");
+  }
+
   return `Failed to ${action} exe.dev VM ${vmName}: ${result.stderr.trim() || result.stdout.trim() || "unknown error"}`;
 }
 
@@ -686,6 +763,10 @@ const plugin = definePlugin({
     ) {
       errors.push("strictHostKeyChecking cannot be empty.");
     }
+    if (config.sshPrivateKey && !isSecretRef(config.sshPrivateKey)) {
+      const sshKeyError = validateSshPrivateKey(config.sshPrivateKey);
+      if (sshKeyError) errors.push(sshKeyError);
+    }
 
     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.",

packages/shared/src/types/plugin.ts

@@ -38,8 +38,24 @@ import type { Routine, RoutineTrigger, RoutineVariable } from "./routine.js";
 /**
  * A JSON Schema object used for plugin config schemas and tool parameter schemas.
  * Plugins provide these as plain JSON Schema compatible objects.
+ *
+ * The Paperclip extension keywords below are recognised by the Paperclip UI
+ * but are otherwise ignored by standard JSON Schema validators.
  */
-export type JsonSchema = Record<string, unknown>;
+export type JsonSchema = {
+  /**
+   * When true, the Paperclip config UI hides this property behind an
+   * "Advanced options" disclosure. Defaults to false (always visible).
+   */
+  "x-paperclip-advanced"?: boolean;
+  /**
+   * Optional sub-section heading used to group advanced properties inside
+   * the disclosure (e.g. "SSH access", "VM resources"). Ignored when
+   * `x-paperclip-advanced` is not true.
+   */
+  "x-paperclip-group"?: string;
+  [key: string]: unknown;
+};
 
 export type {
   PluginDatabaseCoreReadTable,

ui/src/components/JsonSchemaForm.test.tsx

@@ -3,7 +3,7 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { JsonSchemaForm } from "./JsonSchemaForm";
+import { JsonSchemaForm, getDefaultValues } from "./JsonSchemaForm";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
@@ -204,6 +204,177 @@ describe("JsonSchemaForm secret-ref rendering", () => {
     });
   });
 
+  it("renders no Advanced disclosure when no field opts in", async () => {
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <JsonSchemaForm
+          schema={{
+            type: "object",
+            properties: {
+              apiKey: { type: "string", format: "secret-ref" },
+              region: { type: "string" },
+            },
+          }}
+          values={{ apiKey: "", region: "" }}
+          onChange={() => {}}
+        />,
+      );
+    });
+
+    // No disclosure button should be present in the passthrough case.
+    const buttons = Array.from(container.querySelectorAll("button"));
+    const advancedButton = buttons.find((b) =>
+      b.textContent?.includes("Advanced options"),
+    );
+    expect(advancedButton).toBeUndefined();
+
+    // Both fields render in the flat layout: the secret picker (rendered as
+    // a <select> stub) for apiKey and a text input for region.
+    expect(
+      container.querySelector('[data-testid="secret-binding-picker"]'),
+    ).not.toBeNull();
+    expect(container.querySelector('input[type="text"]')).not.toBeNull();
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it("hides advanced fields behind a collapsed disclosure with group headings", async () => {
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <JsonSchemaForm
+          schema={{
+            type: "object",
+            properties: {
+              apiKey: { type: "string", format: "secret-ref" },
+              sshPort: {
+                type: "number",
+                "x-paperclip-advanced": true,
+                "x-paperclip-group": "SSH access",
+              },
+              namePrefix: {
+                type: "string",
+                "x-paperclip-advanced": true,
+              },
+            },
+          }}
+          values={{ apiKey: "", sshPort: 22, namePrefix: "paperclip" }}
+          onChange={() => {}}
+        />,
+      );
+    });
+
+    const buttons = Array.from(container.querySelectorAll("button"));
+    const advancedButton = buttons.find((b) =>
+      b.textContent?.includes("Advanced options"),
+    );
+    expect(advancedButton).toBeDefined();
+    expect(advancedButton!.getAttribute("aria-expanded")).toBe("false");
+
+    // Collapsed: number/text inputs from advanced fields aren't rendered.
+    expect(container.querySelector('input[type="number"]')).toBeNull();
+    // Group headings aren't visible while collapsed.
+    expect(container.textContent).not.toContain("SSH access");
+    expect(container.textContent).not.toContain("More options");
+
+    // Expand and verify both groups + the default bucket appear.
+    await act(async () => {
+      advancedButton!.click();
+    });
+
+    expect(advancedButton!.getAttribute("aria-expanded")).toBe("true");
+    expect(container.querySelector('input[type="number"]')).not.toBeNull();
+    expect(container.textContent).toContain("SSH access");
+    expect(container.textContent).toContain("More options");
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it("force-opens the disclosure when an error lands on a hidden advanced field", async () => {
+    const root = createRoot(container);
+
+    const schema = {
+      type: "object" as const,
+      properties: {
+        apiKey: { type: "string" as const, format: "secret-ref" as const },
+        sshPort: {
+          type: "number" as const,
+          "x-paperclip-advanced": true,
+        },
+      },
+    };
+
+    // No errors -> collapsed
+    await act(async () => {
+      root.render(
+        <JsonSchemaForm
+          schema={schema}
+          values={{ apiKey: "", sshPort: 22 }}
+          onChange={() => {}}
+        />,
+      );
+    });
+
+    let advancedButton = Array.from(container.querySelectorAll("button")).find(
+      (b) => b.textContent?.includes("Advanced options"),
+    );
+    expect(advancedButton!.getAttribute("aria-expanded")).toBe("false");
+
+    // Submit validation error on the hidden advanced field -> forced open
+    await act(async () => {
+      root.render(
+        <JsonSchemaForm
+          schema={schema}
+          values={{ apiKey: "", sshPort: 22 }}
+          onChange={() => {}}
+          errors={{ "/sshPort": "Must be at least 1" }}
+        />,
+      );
+    });
+
+    advancedButton = Array.from(container.querySelectorAll("button")).find(
+      (b) => b.textContent?.includes("Advanced options"),
+    );
+    expect(advancedButton!.getAttribute("aria-expanded")).toBe("true");
+    expect(container.textContent).toContain("Must be at least 1");
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it("omits optional scalar fields from getDefaultValues so empty inputs aren't submitted as 0/''", () => {
+    const defaults = getDefaultValues({
+      type: "object",
+      properties: {
+        apiKey: { type: "string", format: "secret-ref" },
+        sshPort: { type: "number", default: 22 },
+        cpu: { type: "number" },
+        memory: { type: "string" },
+        reuseLease: { type: "boolean", default: false },
+        tags: { type: "array", items: { type: "string" } },
+      },
+    });
+
+    // Fields with explicit defaults round-trip.
+    expect(defaults.sshPort).toBe(22);
+    expect(defaults.reuseLease).toBe(false);
+    expect(defaults.tags).toEqual([]);
+
+    // Optional scalars without explicit defaults stay out of the payload so
+    // the server doesn't see e.g. `cpu: 0` and reject the submission.
+    expect("apiKey" in defaults).toBe(false);
+    expect("cpu" in defaults).toBe(false);
+    expect("memory" in defaults).toBe(false);
+  });
+
   it("keeps the password fallback for short raw values", async () => {
     const root = createRoot(container);
 

ui/src/components/JsonSchemaForm.tsx

@@ -76,6 +76,19 @@ export interface JsonSchemaNode {
   readOnly?: boolean;
   writeOnly?: boolean;
 
+  // Paperclip extensions
+  /**
+   * When true, the field is hidden behind an "Advanced options" disclosure
+   * in the top-level `JsonSchemaForm`. Defaults to false (essential).
+   */
+  "x-paperclip-advanced"?: boolean;
+  /**
+   * Optional sub-section name used to group advanced fields under headings
+   * inside the disclosure (e.g. "SSH access", "VM resources"). Ignored when
+   * `x-paperclip-advanced` is not true.
+   */
+  "x-paperclip-group"?: string;
+
   // Allow extra keys
   [key: string]: unknown;
 }
@@ -121,7 +134,14 @@ export function labelFromKey(key: string, schema: JsonSchemaNode): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-/** Produce a sensible default value for a schema node. */
+/**
+ * Produce a sensible default value for a schema node.
+ *
+ * Optional scalar fields (string, number, integer, secret-ref) without an
+ * explicit `default` return `undefined` so they stay out of the submitted
+ * payload — otherwise an empty field would round-trip as `""` or `0` and
+ * trip server-side "X must be greater than 0 when provided" style validators.
+ */
 export function getDefaultForSchema(schema: JsonSchemaNode): unknown {
   if (schema.default !== undefined) return schema.default;
 
@@ -129,10 +149,9 @@ export function getDefaultForSchema(schema: JsonSchemaNode): unknown {
   switch (type) {
     case "string":
     case "secret-ref":
-      return "";
     case "number":
     case "integer":
-      return schema.minimum ?? 0;
+      return undefined;
     case "boolean":
       return false;
     case "enum":
@@ -143,12 +162,13 @@ export function getDefaultForSchema(schema: JsonSchemaNode): unknown {
       if (!schema.properties) return {};
       const obj: Record<string, unknown> = {};
       for (const [key, propSchema] of Object.entries(schema.properties)) {
-        obj[key] = getDefaultForSchema(propSchema);
+        const def = getDefaultForSchema(propSchema);
+        if (def !== undefined) obj[key] = def;
       }
       return obj;
     }
     default:
-      return "";
+      return undefined;
   }
 }
 
@@ -1138,6 +1158,64 @@ export function JsonSchemaForm({
     [onChange, values],
   );
 
+  const { essentials, advancedGroups, advancedKeys } = useMemo(() => {
+    const essentials: Array<[string, JsonSchemaNode]> = [];
+    // Preserve original key order while bucketing into groups.
+    const groupOrder: string[] = [];
+    const groups = new Map<string, Array<[string, JsonSchemaNode]>>();
+    const advancedKeys = new Set<string>();
+    const DEFAULT_GROUP = "More options";
+
+    for (const entry of Object.entries(properties)) {
+      const [key, propSchema] = entry;
+      if (propSchema["x-paperclip-advanced"] === true) {
+        advancedKeys.add(key);
+        const rawGroup = propSchema["x-paperclip-group"];
+        const group = typeof rawGroup === "string" && rawGroup.length > 0
+          ? rawGroup
+          : DEFAULT_GROUP;
+        if (!groups.has(group)) {
+          groups.set(group, []);
+          groupOrder.push(group);
+        }
+        groups.get(group)!.push(entry);
+      } else {
+        essentials.push(entry);
+      }
+    }
+
+    return {
+      essentials,
+      advancedGroups: groupOrder.map((group) => ({
+        group,
+        fields: groups.get(group)!,
+      })),
+      advancedKeys,
+    };
+  }, [properties]);
+
+  const hasAdvanced = advancedGroups.length > 0;
+
+  const hasAdvancedError = useMemo(() => {
+    if (!hasAdvanced) return false;
+    for (const errorKey of Object.keys(errors)) {
+      // Top-level errors arrive as "/<key>" or "/<key>/<...>".
+      const stripped = errorKey.startsWith("/") ? errorKey.slice(1) : errorKey;
+      const topKey = stripped.split("/")[0];
+      if (advancedKeys.has(topKey)) return true;
+    }
+    return false;
+  }, [errors, advancedKeys, hasAdvanced]);
+
+  const [isAdvancedOpen, setIsAdvancedOpen] = useState(false);
+
+  // Force the disclosure open when a validation error lands on a hidden field
+  // so the user can see and fix it. Never auto-close — once open, the user
+  // controls collapse.
+  useEffect(() => {
+    if (hasAdvancedError) setIsAdvancedOpen(true);
+  }, [hasAdvancedError]);
+
   if (Object.keys(properties).length === 0) {
     return (
       <div
@@ -1151,30 +1229,65 @@ export function JsonSchemaForm({
     );
   }
 
+  const renderField = ([key, propSchema]: [string, JsonSchemaNode]) => {
+    const value = values[key];
+    const isRequired = requiredFields.has(key);
+    const error = errors[`/${key}`];
+    const label = labelFromKey(key, propSchema);
+    const path = `/${key}`;
+
+    return (
+      <FormField
+        key={key}
+        propSchema={propSchema}
+        value={value}
+        onChange={(val) => handleFieldChange(key, val)}
+        error={error}
+        disabled={disabled}
+        label={label}
+        isRequired={isRequired}
+        errors={errors}
+        path={path}
+      />
+    );
+  };
+
   return (
     <div className={cn("space-y-6", className)}>
-      {Object.entries(properties).map(([key, propSchema]) => {
+      {essentials.map(renderField)}
-        const value = values[key];
-        const isRequired = requiredFields.has(key);
-        const error = errors[`/${key}`];
-        const label = labelFromKey(key, propSchema);
-        const path = `/${key}`;
 
-        return (
+      {hasAdvanced && (
-          <FormField
+        <div className="space-y-3 rounded-lg border border-dashed">
-            key={key}
+          <button
-            propSchema={propSchema}
+            type="button"
-            value={value}
+            className="flex w-full items-center justify-between px-4 py-3 text-left"
-            onChange={(val) => handleFieldChange(key, val)}
+            onClick={() => setIsAdvancedOpen((open) => !open)}
-            error={error}
+            aria-expanded={isAdvancedOpen}
-            disabled={disabled}
+          >
-            label={label}
+            <span className="text-sm font-medium">Advanced options</span>
-            isRequired={isRequired}
+            {isAdvancedOpen ? (
-            errors={errors}
+              <ChevronDown className="h-4 w-4 text-muted-foreground" />
-            path={path}
+            ) : (
-          />
+              <ChevronRight className="h-4 w-4 text-muted-foreground" />
-        );
+            )}
-      })}
+          </button>
+
+          {isAdvancedOpen && (
+            <div className="space-y-6 px-4 pb-4">
+              {advancedGroups.map(({ group, fields }) => (
+                <div key={group} className="space-y-4">
+                  <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                    {group}
+                  </div>
+                  <div className="space-y-6">
+                    {fields.map(renderField)}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
     </div>
   );
 }

ui/src/pages/CompanyEnvironments.tsx

@@ -709,7 +709,7 @@ export function CompanyEnvironments() {
             ) : null}
 
             {environmentForm.driver === "sandbox" ? (
-              <div className="grid gap-3 md:grid-cols-2">
+              <div className="space-y-3">
                 <Field label="Provider" hint="Installed run-capable sandbox provider plugins appear here.">
                   <select
                     className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
@@ -736,26 +736,24 @@ export function CompanyEnvironments() {
                     ))}
                   </select>
                 </Field>
-                <div className="md:col-span-2 space-y-3">
+                {selectedSandboxProvider?.description ? (
-                  {selectedSandboxProvider?.description ? (
+                  <div className="text-xs text-muted-foreground">
-                    <div className="text-xs text-muted-foreground">
+                    {selectedSandboxProvider.description}
-                      {selectedSandboxProvider.description}
+                  </div>
-                    </div>
+                ) : null}
-                  ) : null}
+                {selectedSandboxSchema ? (
-                  {selectedSandboxSchema ? (
+                  <JsonSchemaForm
-                    <JsonSchemaForm
+                    schema={selectedSandboxSchema as any}
-                      schema={selectedSandboxSchema as any}
+                    values={environmentForm.sandboxConfig}
-                      values={environmentForm.sandboxConfig}
+                    onChange={(values) =>
-                      onChange={(values) =>
+                      setEnvironmentForm((current) => ({ ...current, sandboxConfig: values }))}
-                        setEnvironmentForm((current) => ({ ...current, sandboxConfig: values }))}
+                    errors={sandboxConfigErrors}
-                      errors={sandboxConfigErrors}
+                  />
-                    />
+                ) : (
-                  ) : (
+                  <div className="rounded-md border border-border/60 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
-                    <div className="rounded-md border border-border/60 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
+                    This provider does not declare additional configuration fields.
-                      This provider does not declare additional configuration fields.
+                  </div>
-                    </div>
+                )}
-                  )}
-                </div>
               </div>
             ) : null}