Generalize sandbox provider core for plugin-only providers (#4449)

## Thinking Path

> - Paperclip is a control plane, so optional execution providers should
sit at the plugin edge instead of hardcoding provider-specific behavior
into core shared/server/ui layers.
> - Sandbox environments are already first-class, and the fake provider
proves the built-in path; the remaining gap was that real providers
still leaked provider-specific config and runtime assumptions into core.
> - That coupling showed up in config normalization, secret persistence,
capabilities reporting, lease reconstruction, and the board UI form
fields.
> - As long as core knew about those provider-shaped details, shipping a
provider as a pure third-party plugin meant every new provider would
still require host changes.
> - This pull request generalizes the sandbox provider seam around
schema-driven plugin metadata and generic secret-ref handling.
> - The runtime and UI now consume provider metadata generically, so
core only special-cases the built-in fake provider while third-party
providers can live entirely in plugins.

## What Changed

- Added generic sandbox-provider capability metadata so plugin-backed
providers can expose `configSchema` through shared environment support
and the environments capabilities API.
- Reworked sandbox config normalization/persistence/runtime resolution
to handle schema-declared secret-ref fields generically, storing them as
Paperclip secrets and resolving them for probe/execute/release flows.
- Generalized plugin sandbox runtime handling so provider validation,
reusable-lease matching, lease reconstruction, and plugin worker calls
all operate on provider-agnostic config instead of provider-shaped
branches.
- Replaced hardcoded sandbox provider form fields in Company Settings
with schema-driven rendering and blocked agent environment selection
from the built-in fake provider.
- Added regression coverage for the generic seam across shared support
helpers plus environment config, probe, routes, runtime, and
sandbox-provider runtime tests.

## Verification

- `pnpm vitest --run packages/shared/src/environment-support.test.ts
server/src/__tests__/environment-config.test.ts
server/src/__tests__/environment-probe.test.ts
server/src/__tests__/environment-routes.test.ts
server/src/__tests__/environment-runtime.test.ts
server/src/__tests__/sandbox-provider-runtime.test.ts`
- `pnpm -r typecheck`

## Risks

- Plugin sandbox providers now depend more heavily on accurate
`configSchema` declarations; incorrect schemas can misclassify
secret-bearing fields or omit required config.
- Reusable lease matching is now metadata-driven for plugin-backed
providers, so providers that fail to persist stable metadata may
reprovision instead of resuming an existing lease.
- The UI form is now fully schema-driven for plugin-backed sandbox
providers; provider manifests without good defaults or descriptions may
produce a rougher operator experience.

## Model Used

- OpenAI Codex via `codex_local`
- Model ID: `gpt-5.4`
- Reasoning effort: `high`
- Context window observed in runtime session metadata: `258400` tokens
- Capabilities used: terminal tool execution, git, and local code/test
inspection

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

packages/shared/src/environment-support.ts

@@ -1,5 +1,6 @@
 import type { AgentAdapterType, EnvironmentDriver } from "./constants.js";
 import type { SandboxEnvironmentProvider } from "./types/environment.js";
+import type { JsonSchema } from "./types/plugin.js";
 
 export type EnvironmentSupportStatus = "supported" | "unsupported";
 
@@ -20,6 +21,7 @@ export interface EnvironmentProviderCapability {
   source?: "builtin" | "plugin";
   pluginKey?: string;
   pluginId?: string;
+  configSchema?: JsonSchema;
 }
 
 export interface EnvironmentCapabilities {
@@ -81,7 +83,7 @@ export function getAdapterEnvironmentSupport(
   const supportedDrivers = new Set(supportedEnvironmentDriversForAdapter(adapterType));
   const supportedProviders = new Set(supportedSandboxProvidersForAdapter(adapterType, additionalSandboxProviders));
   const sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentSupportStatus> = {
-    fake: supportedProviders.has("fake") ? "supported" : "unsupported",
+    fake: "unsupported",
   };
   for (const provider of additionalSandboxProviders) {
     sandboxProviders[provider as SandboxEnvironmentProvider] = supportedProviders.has(provider as SandboxEnvironmentProvider)
@@ -130,6 +132,7 @@ export function getEnvironmentCapabilities(
       source: capability.source ?? "plugin",
       pluginKey: capability.pluginKey,
       pluginId: capability.pluginId,
+      configSchema: capability.configSchema,
     };
   }
   return {

packages/shared/src/types/environment.ts

@@ -22,16 +22,6 @@ export interface SshEnvironmentConfig {
   strictHostKeyChecking: boolean;
 }
 
-/**
- * Known sandbox environment provider keys.
- *
- * `"fake"` is a built-in test-only provider.
- *
- * Additional providers can be added by installing sandbox provider plugins
- * that declare matching `environmentDrivers` in their manifest. The type
- * includes `string` to allow plugin-backed providers without requiring
- * shared type changes.
- */
 export type SandboxEnvironmentProvider = "fake" | (string & {});
 
 export interface FakeSandboxEnvironmentConfig {

server/src/__tests__/environment-config.test.ts

@@ -141,6 +141,26 @@ describe("environment config helpers", () => {
     });
   });
 
+  it("normalizes schema-driven sandbox config into the generic plugin-backed stored shape", () => {
+    const config = normalizeEnvironmentConfig({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "  base  ",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: "450000",
+      },
+    });
+
+    expect(config).toEqual({
+      provider: "secure-plugin",
+      template: "  base  ",
+      apiKey: "22222222-2222-2222-2222-222222222222",
+      timeoutMs: 450000,
+      reuseLease: false,
+    });
+  });
+
   it("normalizes plugin-backed sandbox provider config without server provider changes", () => {
     const config = normalizeEnvironmentConfig({
       driver: "sandbox",
@@ -162,6 +182,30 @@ describe("environment config helpers", () => {
     });
   });
 
+  it("parses a persisted schema-driven sandbox environment into a typed driver config", () => {
+    const parsed = parseEnvironmentDriverConfig({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+
+    expect(parsed).toEqual({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+  });
+
   it("parses a persisted plugin-backed sandbox environment into a typed driver config", () => {
     const parsed = parseEnvironmentDriverConfig({
       driver: "sandbox",

server/src/__tests__/environment-probe.test.ts

@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 const mockEnsureSshWorkspaceReady = vi.hoisted(() => vi.fn());
 const mockProbePluginEnvironmentDriver = vi.hoisted(() => vi.fn());
 const mockProbePluginSandboxProviderDriver = vi.hoisted(() => vi.fn());
+const mockResolvePluginSandboxProviderDriverByKey = vi.hoisted(() => vi.fn());
 
 vi.mock("@paperclipai/adapter-utils/ssh", () => ({
   ensureSshWorkspaceReady: mockEnsureSshWorkspaceReady,
@@ -11,6 +12,7 @@ vi.mock("@paperclipai/adapter-utils/ssh", () => ({
 vi.mock("../services/plugin-environment-driver.js", () => ({
   probePluginEnvironmentDriver: mockProbePluginEnvironmentDriver,
   probePluginSandboxProviderDriver: mockProbePluginSandboxProviderDriver,
+  resolvePluginSandboxProviderDriverByKey: mockResolvePluginSandboxProviderDriverByKey,
 }));
 
 import { probeEnvironment } from "../services/environment-probe.ts";
@@ -20,6 +22,8 @@ describe("probeEnvironment", () => {
     mockEnsureSshWorkspaceReady.mockReset();
     mockProbePluginEnvironmentDriver.mockReset();
     mockProbePluginSandboxProviderDriver.mockReset();
+    mockResolvePluginSandboxProviderDriverByKey.mockReset();
+    mockResolvePluginSandboxProviderDriverByKey.mockResolvedValue(null);
   });
 
   it("reports local environments as immediately available", async () => {

server/src/__tests__/environment-routes.test.ts

@@ -38,6 +38,7 @@ const mockSecretService = vi.hoisted(() => ({
   resolveSecretValue: vi.fn(),
 }));
 const mockValidatePluginEnvironmentDriverConfig = vi.hoisted(() => vi.fn());
+const mockValidatePluginSandboxProviderConfig = vi.hoisted(() => vi.fn());
 const mockListReadyPluginEnvironmentDrivers = vi.hoisted(() => vi.fn());
 const mockExecutionWorkspaceService = vi.hoisted(() => ({}));
 
@@ -69,6 +70,7 @@ vi.mock("../services/execution-workspaces.js", () => ({
 vi.mock("../services/plugin-environment-driver.js", () => ({
   listReadyPluginEnvironmentDrivers: mockListReadyPluginEnvironmentDrivers,
   validatePluginEnvironmentDriverConfig: mockValidatePluginEnvironmentDriverConfig,
+  validatePluginSandboxProviderConfig: mockValidatePluginSandboxProviderConfig,
 }));
 
 function createEnvironment() {
@@ -148,6 +150,18 @@ describe("environment routes", () => {
     });
     mockValidatePluginEnvironmentDriverConfig.mockReset();
     mockValidatePluginEnvironmentDriverConfig.mockImplementation(async ({ config }) => config);
+    mockValidatePluginSandboxProviderConfig.mockReset();
+    mockValidatePluginSandboxProviderConfig.mockImplementation(async ({ provider, config }) => ({
+      normalizedConfig: config,
+      pluginId: `plugin-${provider}`,
+      pluginKey: `plugin.${provider}`,
+      driver: {
+        driverKey: provider,
+        kind: "sandbox_provider",
+        displayName: provider,
+        configSchema: { type: "object" },
+      },
+    }));
     mockListReadyPluginEnvironmentDrivers.mockReset();
     mockListReadyPluginEnvironmentDrivers.mockResolvedValue([]);
   });
@@ -185,6 +199,52 @@ describe("environment routes", () => {
     expect(res.body.sandboxProviders).not.toHaveProperty("fake-plugin");
   });
 
+  it("returns installed plugin-backed sandbox capabilities for environment creation", async () => {
+    mockListReadyPluginEnvironmentDrivers.mockResolvedValue([
+      {
+        pluginId: "plugin-1",
+        pluginKey: "acme.secure-sandbox-provider",
+        driverKey: "secure-plugin",
+        displayName: "Secure Sandbox",
+        description: "Provisions schema-driven cloud sandboxes.",
+        configSchema: {
+          type: "object",
+          properties: {
+            template: { type: "string" },
+            apiKey: { type: "string", format: "secret-ref" },
+          },
+        },
+      },
+    ]);
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "local_implicit",
+    });
+
+    const res = await request(app).get("/api/companies/company-1/environments/capabilities");
+
+    expect(res.status).toBe(200);
+    expect(res.body.sandboxProviders["secure-plugin"]).toMatchObject({
+      status: "supported",
+      supportsRunExecution: true,
+      supportsReusableLeases: true,
+      displayName: "Secure Sandbox",
+      source: "plugin",
+      pluginKey: "acme.secure-sandbox-provider",
+      pluginId: "plugin-1",
+      configSchema: {
+        type: "object",
+        properties: {
+          template: { type: "string" },
+          apiKey: { type: "string", format: "secret-ref" },
+        },
+      },
+    });
+    expect(res.body.adapters.find((row: any) => row.adapterType === "codex_local").sandboxProviders["secure-plugin"])
+      .toBe("supported");
+  });
+
   it("redacts config and metadata for unprivileged agent list reads", async () => {
     mockEnvironmentService.list.mockResolvedValue([createEnvironment()]);
     mockAgentService.getById.mockResolvedValue({
@@ -453,11 +513,12 @@ describe("environment routes", () => {
       },
     };
     mockEnvironmentService.create.mockResolvedValue(environment);
+    const pluginWorkerManager = {};
     const app = createApp({
       type: "board",
       userId: "user-1",
       source: "local_implicit",
-    });
+    }, { pluginWorkerManager });
 
     const res = await request(app)
       .post("/api/companies/company-1/environments")
@@ -531,11 +592,12 @@ describe("environment routes", () => {
       },
     };
     mockEnvironmentService.create.mockResolvedValue(environment);
+    const pluginWorkerManager = {};
     const app = createApp({
       type: "board",
       userId: "user-1",
       source: "local_implicit",
-    });
+    }, { pluginWorkerManager });
 
     const res = await request(app)
       .post("/api/companies/company-1/environments")
@@ -551,6 +613,16 @@ describe("environment routes", () => {
       });
 
     expect(res.status).toBe(201);
+    expect(mockValidatePluginSandboxProviderConfig).toHaveBeenCalledWith({
+      db: expect.anything(),
+      workerManager: pluginWorkerManager,
+      provider: "fake-plugin",
+      config: {
+        image: "fake:test",
+        timeoutMs: 450000,
+        reuseLease: true,
+      },
+    });
     expect(mockEnvironmentService.create).toHaveBeenCalledWith("company-1", {
       name: "Fake plugin Sandbox",
       driver: "sandbox",
@@ -565,6 +637,101 @@ describe("environment routes", () => {
     expect(mockSecretService.create).not.toHaveBeenCalled();
   });
 
+  it("creates a schema-driven sandbox environment with secret-ref fields persisted as secrets", async () => {
+    const environment = {
+      ...createEnvironment(),
+      id: "env-sandbox-secure-plugin",
+      name: "Secure Sandbox",
+      driver: "sandbox" as const,
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "11111111-1111-1111-1111-111111111111",
+        timeoutMs: 450000,
+        reuseLease: true,
+      },
+    };
+    mockEnvironmentService.create.mockResolvedValue(environment);
+    mockValidatePluginSandboxProviderConfig.mockResolvedValue({
+      normalizedConfig: {
+        template: "base",
+        apiKey: "test-provider-key",
+        timeoutMs: 450000,
+        reuseLease: true,
+      },
+      pluginId: "plugin-secure",
+      pluginKey: "acme.secure-sandbox-provider",
+      driver: {
+        driverKey: "secure-plugin",
+        kind: "sandbox_provider",
+        displayName: "Secure Sandbox",
+        configSchema: {
+          type: "object",
+          properties: {
+            template: { type: "string" },
+            apiKey: { type: "string", format: "secret-ref" },
+            timeoutMs: { type: "number" },
+            reuseLease: { type: "boolean" },
+          },
+        },
+      },
+    });
+    const pluginWorkerManager = {};
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "local_implicit",
+    }, { pluginWorkerManager });
+
+    const res = await request(app)
+      .post("/api/companies/company-1/environments")
+      .send({
+        name: "Secure Sandbox",
+        driver: "sandbox",
+        config: {
+          provider: "secure-plugin",
+          template: "  base  ",
+          apiKey: "  test-provider-key  ",
+          timeoutMs: "450000",
+          reuseLease: true,
+        },
+      });
+
+    expect(res.status).toBe(201);
+    expect(mockValidatePluginSandboxProviderConfig).toHaveBeenCalledWith({
+      db: expect.anything(),
+      workerManager: pluginWorkerManager,
+      provider: "secure-plugin",
+      config: {
+        template: "  base  ",
+        apiKey: "  test-provider-key  ",
+        timeoutMs: 450000,
+        reuseLease: true,
+      },
+    });
+    expect(mockEnvironmentService.create).toHaveBeenCalledWith("company-1", {
+      name: "Secure Sandbox",
+      driver: "sandbox",
+      status: "active",
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "11111111-1111-1111-1111-111111111111",
+        timeoutMs: 450000,
+        reuseLease: true,
+      },
+    });
+    expect(JSON.stringify(mockEnvironmentService.create.mock.calls[0][1])).not.toContain("test-provider-key");
+    expect(mockSecretService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({
+        provider: "local_encrypted",
+        value: "test-provider-key",
+      }),
+      expect.any(Object),
+    );
+  });
+
   it("validates plugin environment config through the plugin driver host", async () => {
     const environment = {
       ...createEnvironment(),
@@ -997,12 +1164,13 @@ describe("environment routes", () => {
       summary: "Fake plugin sandbox provider is ready.",
       details: { provider: "fake-plugin" },
     });
+    const pluginWorkerManager = {};
     const app = createApp({
       type: "board",
       userId: "user-1",
       source: "local_implicit",
       runId: "run-1",
-    });
+    }, { pluginWorkerManager });
 
     const res = await request(app)
       .post("/api/companies/company-1/environments/probe-config")
@@ -1031,7 +1199,7 @@ describe("environment routes", () => {
         }),
       }),
       expect.objectContaining({
-        pluginWorkerManager: undefined,
+        pluginWorkerManager,
         resolvedConfig: expect.objectContaining({
           driver: "sandbox",
         }),

server/src/__tests__/environment-runtime.test.ts

@@ -56,6 +56,7 @@ describe("findReusableSandboxLeaseId", () => {
           metadata: {
             provider: "fake-plugin",
             image: "template-a",
+            timeoutMs: 300000,
             reuseLease: true,
           },
         },
@@ -64,13 +65,14 @@ describe("findReusableSandboxLeaseId", () => {
           metadata: {
             provider: "fake-plugin",
             image: "template-b",
+            timeoutMs: 300000,
             reuseLease: true,
           },
         },
       ],
     });
 
-    expect(selected).toBe("sandbox-template-a");
+    expect(selected).toBe("sandbox-template-b");
   });
 
   it("requires image identity for reusable fake sandbox leases", () => {
@@ -476,7 +478,12 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
     const workerManager = {
       isRunning: vi.fn((id: string) => id === pluginId),
       call: vi.fn(async (_pluginId: string, method: string, params: any) => {
-        expect(params.config).toEqual(expect.objectContaining(fakePluginConfig));
+        expect(params.config).toEqual(expect.objectContaining({
+          image: "fake:test",
+          timeoutMs: 1234,
+          reuseLease: false,
+        }));
+        expect(params.config).not.toHaveProperty("provider");
         if (method === "environmentAcquireLease") {
           return {
             providerLeaseId: "sandbox-1",
@@ -499,12 +506,17 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
           };
         }
         if (method === "environmentReleaseLease") {
-          expect(params.config).toEqual(fakePluginConfig);
+          expect(params.config).toEqual({
+            image: "fake:test",
+            timeoutMs: 1234,
+            reuseLease: false,
+          });
           expect(params.config).not.toHaveProperty("driver");
           expect(params.config).not.toHaveProperty("executionWorkspaceMode");
           expect(params.config).not.toHaveProperty("pluginId");
           expect(params.config).not.toHaveProperty("pluginKey");
           expect(params.config).not.toHaveProperty("providerMetadata");
+          expect(params.config).not.toHaveProperty("provider");
           expect(params.config).not.toHaveProperty("sandboxProviderPlugin");
           return undefined;
         }
@@ -543,6 +555,270 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
     expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentReleaseLease", expect.anything());
   });
 
+  it("uses resolved secret-ref config for plugin-backed sandbox execute and release", async () => {
+    const pluginId = randomUUID();
+    const { companyId, environment: baseEnvironment, runId } = await seedEnvironment();
+    const apiSecret = await secretService(db).create(companyId, {
+      name: `secure-plugin-api-key-${randomUUID()}`,
+      provider: "local_encrypted",
+      value: "resolved-provider-key",
+    });
+    const providerConfig = {
+      provider: "secure-plugin",
+      template: "base",
+      apiKey: apiSecret.id,
+      timeoutMs: 1234,
+      reuseLease: false,
+    };
+    const environment = {
+      ...baseEnvironment,
+      name: "Secure Plugin Sandbox",
+      driver: "sandbox",
+      config: providerConfig,
+    };
+    await environmentService(db).update(environment.id, {
+      driver: "sandbox",
+      name: environment.name,
+      config: providerConfig,
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.secure-sandbox-provider",
+      packageName: "@acme/secure-sandbox-provider",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.secure-sandbox-provider",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Secure Sandbox Provider",
+        description: "Test schema-driven provider",
+        author: "Paperclip",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [
+          {
+            driverKey: "secure-plugin",
+            kind: "sandbox_provider",
+            displayName: "Secure Sandbox",
+            configSchema: {
+              type: "object",
+              properties: {
+                template: { type: "string" },
+                apiKey: { type: "string", format: "secret-ref" },
+                timeoutMs: { type: "number" },
+                reuseLease: { type: "boolean" },
+              },
+            },
+          },
+        ],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+    const workerManager = {
+      isRunning: vi.fn((id: string) => id === pluginId),
+      call: vi.fn(async (_pluginId: string, method: string, params: any) => {
+        expect(params.config.apiKey).toBe("resolved-provider-key");
+        expect(params.config).not.toHaveProperty("provider");
+        if (method === "environmentAcquireLease") {
+          return {
+            providerLeaseId: "sandbox-1",
+            metadata: {
+              provider: "secure-plugin",
+              template: "base",
+              apiKey: "resolved-provider-key",
+              timeoutMs: 1234,
+              reuseLease: false,
+              sandboxId: "sandbox-1",
+              remoteCwd: "/workspace",
+            },
+          };
+        }
+        if (method === "environmentExecute") {
+          return {
+            exitCode: 0,
+            signal: null,
+            timedOut: false,
+            stdout: "ok\n",
+            stderr: "",
+          };
+        }
+        if (method === "environmentReleaseLease") {
+          return undefined;
+        }
+        throw new Error(`Unexpected plugin method: ${method}`);
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+
+    const acquired = await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+    expect(acquired.lease.metadata).toMatchObject({
+      provider: "secure-plugin",
+      template: "base",
+      apiKey: apiSecret.id,
+      timeoutMs: 1234,
+      sandboxId: "sandbox-1",
+    });
+    const executed = await runtimeWithPlugin.execute({
+      environment,
+      lease: acquired.lease,
+      command: "printf",
+      args: ["ok"],
+      cwd: "/workspace",
+      env: {},
+      timeoutMs: 1000,
+    });
+
+    await environmentService(db).update(environment.id, {
+      driver: "local",
+      config: {},
+    });
+    const released = await runtimeWithPlugin.releaseRunLeases(runId);
+
+    expect(executed.stdout).toBe("ok\n");
+    expect(released).toHaveLength(1);
+    expect(released[0]?.lease.status).toBe("released");
+    expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentExecute", expect.objectContaining({
+      config: expect.objectContaining({
+        apiKey: "resolved-provider-key",
+      }),
+    }));
+    expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentReleaseLease", expect.objectContaining({
+      config: expect.objectContaining({
+        apiKey: "resolved-provider-key",
+      }),
+    }));
+  });
+
+  it("falls back to acquire when plugin-backed sandbox lease resume throws", async () => {
+    const pluginId = randomUUID();
+    const { companyId, environment: baseEnvironment, runId } = await seedEnvironment();
+    const providerConfig = {
+      provider: "fake-plugin",
+      image: "fake:test",
+      timeoutMs: 1234,
+      reuseLease: true,
+    };
+    const environment = {
+      ...baseEnvironment,
+      name: "Reusable Plugin Sandbox",
+      driver: "sandbox",
+      config: providerConfig,
+    };
+    await environmentService(db).update(environment.id, {
+      driver: "sandbox",
+      name: environment.name,
+      config: providerConfig,
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.fake-sandbox-provider",
+      packageName: "@acme/fake-sandbox-provider",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.fake-sandbox-provider",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Fake Sandbox Provider",
+        description: "Test schema-driven provider",
+        author: "Paperclip",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [
+          {
+            driverKey: "fake-plugin",
+            kind: "sandbox_provider",
+            displayName: "Fake Plugin",
+            configSchema: {
+              type: "object",
+              properties: {
+                image: { type: "string" },
+                timeoutMs: { type: "number" },
+                reuseLease: { type: "boolean" },
+              },
+            },
+          },
+        ],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+    await environmentService(db).acquireLease({
+      companyId,
+      environmentId: environment.id,
+      heartbeatRunId: runId,
+      leasePolicy: "reuse_by_environment",
+      provider: "fake-plugin",
+      providerLeaseId: "stale-plugin-lease",
+      metadata: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        timeoutMs: 1234,
+        reuseLease: true,
+      },
+    });
+
+    const workerManager = {
+      isRunning: vi.fn((id: string) => id === pluginId),
+      call: vi.fn(async (_pluginId: string, method: string) => {
+        if (method === "environmentResumeLease") {
+          throw new Error("stale sandbox");
+        }
+        if (method === "environmentAcquireLease") {
+          return {
+            providerLeaseId: "fresh-plugin-lease",
+            metadata: {
+              provider: "fake-plugin",
+              image: "fake:test",
+              timeoutMs: 1234,
+              reuseLease: true,
+              remoteCwd: "/workspace",
+            },
+          };
+        }
+        throw new Error(`Unexpected plugin method: ${method}`);
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+
+    const acquired = await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+
+    expect(acquired.lease.providerLeaseId).toBe("fresh-plugin-lease");
+    expect(workerManager.call).toHaveBeenNthCalledWith(1, pluginId, "environmentResumeLease", expect.objectContaining({
+      driverKey: "fake-plugin",
+      providerLeaseId: "stale-plugin-lease",
+    }));
+    expect(workerManager.call).toHaveBeenNthCalledWith(2, pluginId, "environmentAcquireLease", expect.objectContaining({
+      driverKey: "fake-plugin",
+      config: {
+        image: "fake:test",
+        timeoutMs: 1234,
+        reuseLease: true,
+      },
+      runId,
+    }));
+  });
+
   it("releases a sandbox run lease from metadata after the environment config changes", async () => {
     const { companyId, environment, runId } = await seedEnvironment({
       driver: "sandbox",

server/src/__tests__/json-schema-secret-refs.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { collectSecretRefPaths } from "../services/json-schema-secret-refs.ts";
+
+describe("collectSecretRefPaths", () => {
+  it("collects nested secret-ref paths from object properties", () => {
+    expect(Array.from(collectSecretRefPaths({
+      type: "object",
+      properties: {
+        credentials: {
+          type: "object",
+          properties: {
+            apiKey: { type: "string", format: "secret-ref" },
+          },
+        },
+      },
+    }))).toEqual(["credentials.apiKey"]);
+  });
+
+  it("collects secret-ref paths from JSON Schema composition keywords", () => {
+    expect(Array.from(collectSecretRefPaths({
+      type: "object",
+      allOf: [
+        {
+          properties: {
+            apiKey: { type: "string", format: "secret-ref" },
+          },
+        },
+        {
+          properties: {
+            nested: {
+              oneOf: [
+                {
+                  properties: {
+                    token: { type: "string", format: "secret-ref" },
+                  },
+                },
+              ],
+            },
+          },
+        },
+      ],
+    })).sort()).toEqual(["apiKey", "nested.token"]);
+  });
+});

server/src/__tests__/sandbox-provider-runtime.test.ts

@@ -109,6 +109,41 @@ describe("sandbox provider runtime", () => {
     ).toBe("sandbox-image-b");
   });
 
+  it("matches reusable plugin leases by persisted config fields", () => {
+    expect(
+      findReusableSandboxProviderLeaseId({
+        config: {
+          provider: "secure-plugin",
+          template: "template-b",
+          apiKey: "22222222-2222-2222-2222-222222222222",
+          timeoutMs: 300000,
+          reuseLease: true,
+        },
+        leases: [
+          {
+            providerLeaseId: "sandbox-template-a",
+            metadata: {
+              provider: "secure-plugin",
+              template: "template-a",
+              apiKey: "11111111-1111-1111-1111-111111111111",
+              reuseLease: true,
+            },
+          },
+          {
+            providerLeaseId: "sandbox-template-b",
+            metadata: {
+              provider: "secure-plugin",
+              template: "template-b",
+              apiKey: "22222222-2222-2222-2222-222222222222",
+              timeoutMs: 300000,
+              reuseLease: true,
+            },
+          },
+        ],
+      }),
+    ).toBe("sandbox-template-b");
+  });
+
   it("reconstructs fake sandbox config from lease metadata for later release", () => {
     const metadata = {
       provider: "fake",
@@ -146,6 +181,31 @@ describe("sandbox provider runtime", () => {
     });
   });
 
+  it("reconstructs plugin-backed secret-ref config from lease metadata for later release", () => {
+    expect(sandboxConfigFromLeaseMetadata({
+      metadata: {
+        provider: "secure-plugin",
+        template: "paperclip-template",
+      },
+    })).toBeNull();
+
+    expect(sandboxConfigFromLeaseMetadataLoose({
+      metadata: {
+        provider: "secure-plugin",
+        template: "paperclip-template",
+        timeoutMs: 120000,
+        reuseLease: true,
+        apiKey: "11111111-1111-1111-1111-111111111111",
+      },
+    })).toEqual({
+      provider: "secure-plugin",
+      template: "paperclip-template",
+      apiKey: "11111111-1111-1111-1111-111111111111",
+      timeoutMs: 120000,
+      reuseLease: true,
+    });
+  });
+
   it("releases fake leases without external side effects", async () => {
     await expect(releaseSandboxProviderLease({
       config: {

server/src/routes/environments.ts

@@ -184,6 +184,7 @@ export function environmentRoutes(
             source: "plugin" as const,
             pluginKey: driver.pluginKey,
             pluginId: driver.pluginId,
+            configSchema: driver.configSchema,
           },
         ])),
       },
@@ -409,9 +410,11 @@ export function environmentRoutes(
       const companyId = req.params.companyId as string;
       await assertCanMutateEnvironments(req, companyId);
       const actor = getActorInfo(req);
-      const normalizedConfig = normalizeEnvironmentConfigForProbe({
+      const normalizedConfig = await normalizeEnvironmentConfigForProbe({
+        db,
         driver: req.body.driver,
         config: req.body.config,
+        pluginWorkerManager: options.pluginWorkerManager,
       });
       const environment = {
         id: "unsaved",

server/src/services/environment-config.ts

@@ -6,16 +6,26 @@ import type {
   EnvironmentDriver,
   FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
-  PluginSandboxEnvironmentConfig,
   PluginEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
   SandboxEnvironmentConfig,
   SshEnvironmentConfig,
 } from "@paperclipai/shared";
 import { unprocessable } from "../errors.js";
 import { parseObject } from "../adapters/utils.js";
 import { secretService } from "./secrets.js";
-import { validatePluginEnvironmentDriverConfig } from "./plugin-environment-driver.js";
+import {
+  resolvePluginSandboxProviderDriverByKey,
+  validatePluginEnvironmentDriverConfig,
+  validatePluginSandboxProviderConfig,
+} from "./plugin-environment-driver.js";
 import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import {
+  collectSecretRefPaths,
+  isUuidSecretRef,
+  readConfigValueAtPath,
+  writeConfigValueAtPath,
+} from "./json-schema-secret-refs.js";
 
 const secretRefSchema = z.object({
   type: z.literal("secret_ref"),
@@ -43,6 +53,17 @@ const sshEnvironmentConfigSchema = z.object({
   strictHostKeyChecking: z.boolean().optional().default(true),
 }).strict();
 
+const sshEnvironmentConfigProbeSchema = sshEnvironmentConfigSchema.extend({
+  privateKey: z
+    .string()
+    .trim()
+    .optional()
+    .nullable()
+    .transform((value) => (value && value.length > 0 ? value : null)),
+}).strict();
+
+const sshEnvironmentConfigPersistenceSchema = sshEnvironmentConfigProbeSchema;
+
 const fakeSandboxEnvironmentConfigSchema = z.object({
   provider: z.literal("fake").default("fake"),
   image: z
@@ -59,10 +80,7 @@ const pluginSandboxProviderKeySchema = z.string()
   .regex(
     /^[a-z0-9][a-z0-9._-]*$/,
     "Sandbox provider key must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, hyphens, or underscores",
-  )
+  );
-  .refine((value) => value !== "fake", {
-    message: "Built-in sandbox providers must use their dedicated config schema.",
-  });
 
 const pluginSandboxEnvironmentConfigSchema = z.object({
   provider: pluginSandboxProviderKeySchema,
@@ -70,8 +88,6 @@ const pluginSandboxEnvironmentConfigSchema = z.object({
   reuseLease: z.boolean().optional().default(false),
 }).catchall(z.unknown());
 
-type SandboxConfigSchemaMode = "stored" | "probe" | "persistence";
-
 const pluginEnvironmentConfigSchema = z.object({
   pluginKey: z.string().min(1),
   driverKey: z.string().min(1).regex(
@@ -99,7 +115,6 @@ function getSandboxProvider(raw: Record<string, unknown>) {
 
 function parseSandboxEnvironmentConfig(
   input: Record<string, unknown> | null | undefined,
-  mode: SandboxConfigSchemaMode,
 ) {
   const raw = parseObject(input);
   const provider = getSandboxProvider(raw);
@@ -117,16 +132,19 @@ function parseSandboxEnvironmentConfig(
     : ({ success: false as const, error: parsed.error });
 }
 
-const sshEnvironmentConfigProbeSchema = sshEnvironmentConfigSchema.extend({
+async function getSandboxProviderConfigSchema(
-  privateKey: z
+  db: Db,
-    .string()
+  provider: string,
-    .trim()
+): Promise<Record<string, unknown> | null> {
-    .optional()
+  const resolved = await resolvePluginSandboxProviderDriverByKey({
-    .nullable()
+    db,
-    .transform((value) => (value && value.length > 0 ? value : null)),
+    driverKey: provider,
-}).strict();
+  });
-
+  const schema = resolved?.driver.configSchema;
-const sshEnvironmentConfigPersistenceSchema = sshEnvironmentConfigProbeSchema;
+  return schema && typeof schema === "object" && !Array.isArray(schema)
+    ? schema as Record<string, unknown>
+    : null;
+}
 
 function secretName(input: {
   environmentName: string;
@@ -167,6 +185,69 @@ async function createEnvironmentSecret(input: {
   };
 }
 
+async function persistConfigSecretRefs(input: {
+  db: Db;
+  companyId: string;
+  environmentName: string;
+  driver: EnvironmentDriver;
+  config: Record<string, unknown>;
+  schema: Record<string, unknown> | null;
+  actor?: { userId?: string | null; agentId?: string | null };
+}): Promise<Record<string, unknown>> {
+  let nextConfig = { ...input.config };
+  for (const path of collectSecretRefPaths(input.schema)) {
+    const rawValue = readConfigValueAtPath(nextConfig, path);
+    if (typeof rawValue !== "string") continue;
+    const trimmed = rawValue.trim();
+    if (trimmed.length === 0) {
+      nextConfig = writeConfigValueAtPath(nextConfig, path, undefined);
+      continue;
+    }
+    if (isUuidSecretRef(trimmed)) {
+      nextConfig = writeConfigValueAtPath(nextConfig, path, trimmed);
+      continue;
+    }
+    const created = await createEnvironmentSecret({
+      db: input.db,
+      companyId: input.companyId,
+      environmentName: input.environmentName,
+      driver: input.driver,
+      field: path.replace(/[^a-z0-9]+/gi, "-").toLowerCase(),
+      value: trimmed,
+      actor: input.actor,
+    });
+    nextConfig = writeConfigValueAtPath(nextConfig, path, created.secretId);
+  }
+  return nextConfig;
+}
+
+async function resolveConfigSecretRefsForRuntime(input: {
+  db: Db;
+  companyId: string;
+  config: Record<string, unknown>;
+  schema: Record<string, unknown> | null;
+}): Promise<Record<string, unknown>> {
+  const secrets = secretService(input.db);
+  let nextConfig = { ...input.config };
+  for (const path of collectSecretRefPaths(input.schema)) {
+    const current = readConfigValueAtPath(nextConfig, path);
+    if (typeof current !== "string") continue;
+    const trimmed = current.trim();
+    if (!isUuidSecretRef(trimmed)) continue;
+    nextConfig = writeConfigValueAtPath(
+      nextConfig,
+      path,
+      await secrets.resolveSecretValue(input.companyId, trimmed, "latest"),
+    );
+  }
+  return nextConfig;
+}
+
+export function stripSandboxProviderEnvelope(config: SandboxEnvironmentConfig): Record<string, unknown> {
+  const { provider: _provider, ...driverConfig } = config as Record<string, unknown>;
+  return driverConfig;
+}
+
 export function normalizeEnvironmentConfig(input: {
   driver: EnvironmentDriver;
   config: Record<string, unknown> | null | undefined;
@@ -186,7 +267,7 @@ export function normalizeEnvironmentConfig(input: {
   }
 
   if (input.driver === "sandbox") {
-    const parsed = parseSandboxEnvironmentConfig(input.config, "stored");
+    const parsed = parseSandboxEnvironmentConfig(input.config);
     if (!parsed.success) {
       throw unprocessable(toErrorMessage(parsed.error), {
         issues: parsed.error.issues,
@@ -209,9 +290,11 @@ export function normalizeEnvironmentConfig(input: {
 }
 
 export function normalizeEnvironmentConfigForProbe(input: {
+  db: Db;
   driver: EnvironmentDriver;
   config: Record<string, unknown> | null | undefined;
-}): Record<string, unknown> {
+  pluginWorkerManager?: PluginWorkerManager;
+}): Promise<Record<string, unknown>> | Record<string, unknown> {
   if (input.driver === "ssh") {
     const parsed = sshEnvironmentConfigProbeSchema.safeParse(parseObject(input.config));
     if (!parsed.success) {
@@ -223,16 +306,33 @@ export function normalizeEnvironmentConfigForProbe(input: {
   }
 
   if (input.driver === "sandbox") {
-    const parsed = parseSandboxEnvironmentConfig(input.config, "probe");
+    const parsed = parseSandboxEnvironmentConfig(input.config);
     if (!parsed.success) {
       throw unprocessable(toErrorMessage(parsed.error), {
         issues: parsed.error.issues,
       });
     }
+    if (parsed.data.provider === "fake") {
       return parsed.data;
     }
+    if (!input.pluginWorkerManager) {
+      throw unprocessable("Sandbox provider config validation requires a running plugin worker manager.");
+    }
+    return validatePluginSandboxProviderConfig({
+      db: input.db,
+      workerManager: input.pluginWorkerManager,
+      provider: parsed.data.provider,
+      config: stripSandboxProviderEnvelope(parsed.data),
+    }).then((validated) => ({
+      provider: parsed.data.provider,
+      ...validated.normalizedConfig,
+    }));
+  }
 
-  return normalizeEnvironmentConfig(input);
+  return normalizeEnvironmentConfig({
+    driver: input.driver,
+    config: input.config,
+  });
 }
 
 export async function normalizeEnvironmentConfigForPersistence(input: {
@@ -279,19 +379,41 @@ export async function normalizeEnvironmentConfigForPersistence(input: {
   }
 
   if (input.driver === "sandbox") {
-    const parsed = parseSandboxEnvironmentConfig(input.config, "persistence");
+    const parsed = parseSandboxEnvironmentConfig(input.config);
     if (!parsed.success) {
       throw unprocessable(toErrorMessage(parsed.error), {
         issues: parsed.error.issues,
       });
     }
-    const sandboxConfig = parsed.data;
+    if (parsed.data.provider === "fake") {
-    if (sandboxConfig.provider === "fake") {
       throw unprocessable(
         "Built-in fake sandbox environments are reserved for internal probes and cannot be saved.",
       );
     }
-    return { ...(sandboxConfig as PluginSandboxEnvironmentConfig) };
+    if (!input.pluginWorkerManager) {
+      throw unprocessable("Sandbox provider config validation requires a running plugin worker manager.");
+    }
+    const validated = await validatePluginSandboxProviderConfig({
+      db: input.db,
+      workerManager: input.pluginWorkerManager,
+      provider: parsed.data.provider,
+      config: stripSandboxProviderEnvelope(parsed.data),
+    });
+    return await persistConfigSecretRefs({
+      db: input.db,
+      companyId: input.companyId,
+      environmentName: input.environmentName,
+      driver: input.driver,
+      config: {
+        provider: parsed.data.provider,
+        ...validated.normalizedConfig,
+      },
+      schema:
+        validated.driver.configSchema && typeof validated.driver.configSchema === "object" && !Array.isArray(validated.driver.configSchema)
+          ? validated.driver.configSchema as Record<string, unknown>
+          : null,
+      actor: input.actor,
+    });
   }
 
   if (input.driver === "plugin") {
@@ -339,6 +461,18 @@ export async function resolveEnvironmentDriverConfigForRuntime(
     };
   }
 
+  if (parsed.driver === "sandbox" && parsed.config.provider !== "fake") {
+    return {
+      driver: "sandbox",
+      config: await resolveConfigSecretRefsForRuntime({
+        db,
+        companyId,
+        config: parsed.config as Record<string, unknown>,
+        schema: await getSandboxProviderConfigSchema(db, parsed.config.provider),
+      }) as SandboxEnvironmentConfig,
+    };
+  }
+
   return parsed;
 }
 
@@ -370,7 +504,7 @@ export function parseEnvironmentDriverConfig(
   }
 
   if (environment.driver === "sandbox") {
-    const parsed = parseSandboxEnvironmentConfig(environment.config, "stored");
+    const parsed = parseSandboxEnvironmentConfig(environment.config);
     if (!parsed.success) {
       throw parsed.error;
     }

server/src/services/environment-runtime.ts

@@ -16,7 +16,11 @@ import type {
 } from "@paperclipai/plugin-sdk";
 import { ensureSshWorkspaceReady, findReachablePaperclipApiUrlOverSsh } from "@paperclipai/adapter-utils/ssh";
 import { environmentService } from "./environments.js";
-import { parseEnvironmentDriverConfig, resolveEnvironmentDriverConfigForRuntime } from "./environment-config.js";
+import {
+  parseEnvironmentDriverConfig,
+  resolveEnvironmentDriverConfigForRuntime,
+  stripSandboxProviderEnvelope,
+} from "./environment-config.js";
 import {
   acquireSandboxProviderLease,
   findReusableSandboxProviderLeaseId,
@@ -31,8 +35,10 @@ import {
   destroyPluginEnvironmentLease,
   executePluginEnvironmentCommand,
   realizePluginEnvironmentWorkspace,
+  resolvePluginSandboxProviderDriverByKey,
   resumePluginEnvironmentLease,
 } from "./plugin-environment-driver.js";
+import { collectSecretRefPaths } from "./json-schema-secret-refs.js";
 import { buildWorkspaceRealizationRecordFromDriverInput } from "./workspace-realization.js";
 
 export function buildEnvironmentLeaseContext(input: {
@@ -44,6 +50,53 @@ export function buildEnvironmentLeaseContext(input: {
   };
 }
 
+function stripSecretRefValuesFromPluginLeaseMetadata(input: {
+  metadata: Record<string, unknown> | null | undefined;
+  schema: Record<string, unknown> | null | undefined;
+}): Record<string, unknown> {
+  const sanitized = structuredClone(input.metadata ?? {}) as Record<string, unknown>;
+
+  for (const path of collectSecretRefPaths(input.schema)) {
+    const keys = path.split(".");
+    const parents: Array<{ container: Record<string, unknown>; key: string }> = [];
+    let cursor: Record<string, unknown> | null = sanitized;
+
+    for (let index = 0; index < keys.length - 1; index += 1) {
+      const key = keys[index]!;
+      const next = cursor?.[key];
+      if (!next || typeof next !== "object" || Array.isArray(next)) {
+        cursor = null;
+        break;
+      }
+      parents.push({ container: cursor, key });
+      cursor = next as Record<string, unknown>;
+    }
+
+    if (!cursor) continue;
+
+    const leafKey = keys[keys.length - 1]!;
+    if (!Object.prototype.hasOwnProperty.call(cursor, leafKey)) continue;
+    delete cursor[leafKey];
+
+    for (let index = parents.length - 1; index >= 0; index -= 1) {
+      const { container, key } = parents[index]!;
+      const value = container[key];
+      if (
+        value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value as Record<string, unknown>).length === 0
+      ) {
+        delete container[key];
+      } else {
+        break;
+      }
+    }
+  }
+
+  return sanitized;
+}
+
 export interface EnvironmentDriverAcquireInput {
   companyId: string;
   environment: Environment;
@@ -238,33 +291,6 @@ function createSandboxEnvironmentDriver(
   pluginWorkerManager?: PluginWorkerManager,
 ): EnvironmentRuntimeDriver {
   const environmentsSvc = environmentService(db);
-  const pluginRegistry = pluginRegistryService(db);
-
-  /**
-   * Resolve a sandbox provider plugin by looking up a plugin whose manifest
-   * declares an environment driver with a matching driverKey. Returns null
-   * if no matching plugin is found or the worker isn't running.
-   */
-  async function resolvePluginForProvider(
-    provider: string,
-  ): Promise<{ pluginId: string; pluginKey: string } | null> {
-    if (!pluginWorkerManager) return null;
-    const plugins = await pluginRegistry.list();
-    for (const plugin of plugins) {
-      if (plugin.status !== "ready") continue;
-      const drivers = plugin.manifestJson.environmentDrivers ?? [];
-      for (const driver of drivers) {
-        if (
-          driver.driverKey === provider &&
-          driver.kind === "sandbox_provider" &&
-          pluginWorkerManager.isRunning(plugin.id)
-        ) {
-          return { pluginId: plugin.id, pluginKey: plugin.pluginKey };
-        }
-      }
-    }
-    return null;
-  }
 
   async function resolvePluginSandboxRuntimeConfig(input: {
     environment: Environment;
@@ -308,29 +334,64 @@ function createSandboxEnvironmentDriver(
     driver: "sandbox",
 
     async acquireRunLease(input) {
+      const storedParsed = parseEnvironmentDriverConfig(input.environment);
       const parsed = await resolveEnvironmentDriverConfigForRuntime(db, input.companyId, input.environment);
-      if (parsed.driver !== "sandbox") {
+      if (parsed.driver !== "sandbox" || storedParsed.driver !== "sandbox") {
         throw new Error(`Expected sandbox environment config for driver "${input.environment.driver}".`);
       }
 
       // Check if this provider should be handled by a plugin.
       if (!isBuiltinSandboxProvider(parsed.config.provider)) {
-        const pluginProvider = await resolvePluginForProvider(parsed.config.provider);
+        const pluginProvider = await resolvePluginSandboxProviderDriverByKey({
+          db,
+          driverKey: parsed.config.provider,
+          workerManager: pluginWorkerManager,
+          requireRunning: true,
+        });
         if (!pluginProvider || !pluginWorkerManager) {
           throw new Error(
             `Sandbox provider "${parsed.config.provider}" is not registered as a built-in provider and no matching plugin is available.`,
           );
         }
 
-        // Delegate to the plugin worker for lease acquisition.
+        const workerConfig = stripSandboxProviderEnvelope(parsed.config);
-        const providerLease = await pluginWorkerManager.call(
+        const storedConfig = storedParsed.config;
-          pluginProvider.pluginId,
+        const existingLeases = parsed.config.reuseLease
+          ? await environmentsSvc.listLeases(input.environment.id)
+          : [];
+        const reusableProviderLeaseId = parsed.config.reuseLease
+          ? findReusableSandboxLeaseId({ config: storedConfig, leases: existingLeases })
+          : null;
+        const reusableLease = reusableProviderLeaseId
+          ? existingLeases.find((lease) => lease.providerLeaseId === reusableProviderLeaseId)
+          : null;
+
+        const providerLease = reusableLease?.providerLeaseId
+          ? await pluginWorkerManager.call(
+              pluginProvider.plugin.id,
+              "environmentResumeLease",
+              {
+                driverKey: parsed.config.provider,
+                companyId: input.companyId,
+                environmentId: input.environment.id,
+                config: workerConfig,
+                providerLeaseId: reusableLease.providerLeaseId,
+                leaseMetadata: reusableLease.metadata ?? undefined,
+              },
+            ).then((resumed) =>
+              typeof resumed.providerLeaseId === "string" && resumed.providerLeaseId.length > 0
+                ? resumed
+                : null,
+            ).catch(() => null)
+          : null;
+        const acquiredLease = providerLease ?? await pluginWorkerManager.call(
+          pluginProvider.plugin.id,
           "environmentAcquireLease",
           {
             driverKey: parsed.config.provider,
             companyId: input.companyId,
             environmentId: input.environment.id,
-            config: parsed.config as unknown as Record<string, unknown>,
+            config: workerConfig,
             runId: input.heartbeatRunId,
             workspaceMode: input.executionWorkspaceMode ?? undefined,
           },
@@ -348,16 +409,19 @@ function createSandboxEnvironmentDriver(
           heartbeatRunId: input.heartbeatRunId,
           leasePolicy: resolvedLeasePolicy,
           provider: parsed.config.provider,
-          providerLeaseId: providerLease.providerLeaseId,
+          providerLeaseId: acquiredLease.providerLeaseId,
-          expiresAt: providerLease.expiresAt ? new Date(providerLease.expiresAt) : undefined,
+          expiresAt: acquiredLease.expiresAt ? new Date(acquiredLease.expiresAt) : undefined,
           metadata: {
             driver: input.environment.driver,
             executionWorkspaceMode: input.executionWorkspaceMode,
-            pluginId: pluginProvider.pluginId,
+            pluginId: pluginProvider.plugin.id,
-            pluginKey: pluginProvider.pluginKey,
+            pluginKey: pluginProvider.plugin.pluginKey,
             sandboxProviderPlugin: true,
-            ...sandboxConfigForLeaseMetadata(parsed.config),
+            ...sandboxConfigForLeaseMetadata(storedConfig),
-            ...(providerLease.metadata ?? {}),
+            ...stripSecretRefValuesFromPluginLeaseMetadata({
+              metadata: acquiredLease.metadata,
+              schema: pluginProvider.driver.configSchema as Record<string, unknown> | null | undefined,
+            }),
           },
         });
       }
@@ -462,7 +526,7 @@ function createSandboxEnvironmentDriver(
             driverKey: providerKey,
             companyId: input.lease.companyId,
             environmentId: input.environment.id,
-            config,
+            config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
             lease: {
               providerLeaseId: input.lease.providerLeaseId,
               metadata: input.lease.metadata ?? undefined,
@@ -505,7 +569,7 @@ function createSandboxEnvironmentDriver(
             driverKey: providerKey,
             companyId: input.lease.companyId,
             environmentId: input.environment.id,
-            config,
+            config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
             lease: {
               providerLeaseId: input.lease.providerLeaseId,
               metadata: input.lease.metadata ?? undefined,
@@ -543,7 +607,7 @@ function createSandboxEnvironmentDriver(
           driverKey: providerKey,
           companyId: input.lease.companyId,
           environmentId: input.environment.id,
-          config,
+          config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
           providerLeaseId: input.lease.providerLeaseId,
           leaseMetadata: metadata,
         });

server/src/services/json-schema-secret-refs.ts

@@ -0,0 +1,79 @@
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isUuidSecretRef(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+export function collectSecretRefPaths(
+  schema: Record<string, unknown> | null | undefined,
+): Set<string> {
+  const paths = new Set<string>();
+  if (!schema || typeof schema !== "object") return paths;
+
+  function walk(node: Record<string, unknown>, prefix: string): void {
+    for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+      const branches = node[keyword];
+      if (!Array.isArray(branches)) continue;
+      for (const branch of branches) {
+        if (!branch || typeof branch !== "object" || Array.isArray(branch)) continue;
+        walk(branch as Record<string, unknown>, prefix);
+      }
+    }
+
+    const properties = node.properties as Record<string, Record<string, unknown>> | undefined;
+    if (!properties || typeof properties !== "object") return;
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (!propertySchema || typeof propertySchema !== "object") continue;
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (propertySchema.format === "secret-ref") {
+        paths.add(path);
+      }
+      walk(propertySchema, path);
+    }
+  }
+
+  walk(schema, "");
+  return paths;
+}
+
+export function readConfigValueAtPath(
+  config: Record<string, unknown>,
+  dotPath: string,
+): unknown {
+  let current: unknown = config;
+  for (const key of dotPath.split(".")) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+export function writeConfigValueAtPath(
+  config: Record<string, unknown>,
+  dotPath: string,
+  value: unknown,
+): Record<string, unknown> {
+  const result = structuredClone(config) as Record<string, unknown>;
+  const keys = dotPath.split(".");
+  let cursor: Record<string, unknown> = result;
+
+  for (let index = 0; index < keys.length - 1; index += 1) {
+    const key = keys[index]!;
+    const next = cursor[key];
+    if (!next || typeof next !== "object" || Array.isArray(next)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key] as Record<string, unknown>;
+  }
+
+  const leafKey = keys[keys.length - 1]!;
+  if (value === undefined) {
+    delete cursor[leafKey];
+  } else {
+    cursor[leafKey] = value;
+  }
+  return result;
+}

server/src/services/plugin-environment-driver.ts

@@ -1,5 +1,9 @@
 import type { Db } from "@paperclipai/db";
-import type { EnvironmentProbeResult, PluginEnvironmentConfig } from "@paperclipai/shared";
+import type {
+  EnvironmentProbeResult,
+  PluginEnvironmentConfig,
+  PluginEnvironmentDriverDeclaration,
+} from "@paperclipai/shared";
 import type {
   PluginEnvironmentExecuteParams,
   PluginEnvironmentExecuteResult,
@@ -42,15 +46,31 @@ export async function resolvePluginEnvironmentDriverByKey(input: {
   workerManager: PluginWorkerManager;
   driverKey: string;
 }) {
+  return await resolvePluginSandboxProviderDriverByKey({
+    db: input.db,
+    driverKey: input.driverKey,
+    workerManager: input.workerManager,
+    requireRunning: true,
+  });
+}
+
+export async function resolvePluginSandboxProviderDriverByKey(input: {
+  db: Db;
+  driverKey: string;
+  workerManager?: PluginWorkerManager;
+  requireRunning?: boolean;
+}): Promise<{ plugin: Awaited<ReturnType<ReturnType<typeof pluginRegistryService>["list"]>>[number]; driver: PluginEnvironmentDriverDeclaration } | null> {
   const pluginRegistry = pluginRegistryService(input.db);
   const plugins = await pluginRegistry.list();
   for (const plugin of plugins) {
-    if (plugin.status !== "ready") continue;
     const driver = plugin.manifestJson.environmentDrivers?.find(
       (candidate) => candidate.driverKey === input.driverKey && candidate.kind === "sandbox_provider",
-    );
+    ) as PluginEnvironmentDriverDeclaration | undefined;
     if (!driver) continue;
-    if (!input.workerManager.isRunning(plugin.id)) continue;
+    if (input.requireRunning) {
+      if (plugin.status !== "ready") continue;
+      if (!input.workerManager?.isRunning(plugin.id)) continue;
+    }
     return { plugin, driver };
   }
   return null;
@@ -73,10 +93,55 @@ export async function listReadyPluginEnvironmentDrivers(input: {
         driverKey: driver.driverKey,
         displayName: driver.displayName,
         description: driver.description,
+        configSchema: driver.configSchema,
       }));
   });
 }
 
+export async function validatePluginSandboxProviderConfig(input: {
+  db: Db;
+  workerManager: PluginWorkerManager;
+  provider: string;
+  config: Record<string, unknown>;
+}): Promise<{
+  normalizedConfig: Record<string, unknown>;
+  pluginId: string;
+  pluginKey: string;
+  driver: PluginEnvironmentDriverDeclaration;
+}> {
+  const resolved = await resolvePluginSandboxProviderDriverByKey({
+    db: input.db,
+    driverKey: input.provider,
+    workerManager: input.workerManager,
+    requireRunning: true,
+  });
+  if (!resolved) {
+    throw unprocessable(`Sandbox provider "${input.provider}" is not installed or its plugin worker is not running.`);
+  }
+
+  const result = await input.workerManager.call(resolved.plugin.id, "environmentValidateConfig", {
+    driverKey: input.provider,
+    config: input.config,
+  });
+
+  if (!result.ok) {
+    throw unprocessable(
+      result.errors?.[0] ?? `Sandbox provider "${input.provider}" rejected its config.`,
+      {
+        errors: result.errors ?? [],
+        warnings: result.warnings ?? [],
+      },
+    );
+  }
+
+  return {
+    normalizedConfig: result.normalizedConfig ?? input.config,
+    pluginId: resolved.plugin.id,
+    pluginKey: resolved.plugin.pluginKey,
+    driver: resolved.driver,
+  };
+}
+
 export async function validatePluginEnvironmentDriverConfig(input: {
   db: Db;
   workerManager: PluginWorkerManager;
@@ -156,11 +221,12 @@ export async function probePluginSandboxProviderDriver(input: {
     };
   }
 
+  const { provider: _provider, ...driverConfig } = input.config;
   const result = await input.workerManager.call(resolved.plugin.id, "environmentProbe", {
     driverKey: input.provider,
     companyId: input.companyId,
     environmentId: input.environmentId,
-    config: input.config,
+    config: driverConfig,
   });
 
   return {

server/src/services/plugin-secrets-handler.ts

@@ -39,6 +39,11 @@ import { companySecrets, companySecretVersions, pluginConfig } from "@paperclipa
 import type { SecretProvider } from "@paperclipai/shared";
 import { getSecretProvider } from "../secrets/provider-registry.js";
 import { pluginRegistryService } from "./plugin-registry.js";
+import {
+  collectSecretRefPaths,
+  isUuidSecretRef,
+  readConfigValueAtPath,
+} from "./json-schema-secret-refs.js";
 
 // ---------------------------------------------------------------------------
 // Error helpers
@@ -70,48 +75,6 @@ function invalidSecretRef(secretRef: string): Error {
 // Validation
 // ---------------------------------------------------------------------------
 
-/** UUID v4 regex for validating secretRef format. */
-const UUID_RE =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Check whether a secretRef looks like a valid UUID.
- */
-function isUuid(value: string): boolean {
-  return UUID_RE.test(value);
-}
-
-/**
- * Collect the property paths (dot-separated keys) whose schema node declares
- * `format: "secret-ref"`. Only top-level and nested `properties` are walked —
- * this mirrors the flat/nested object shapes that `JsonSchemaForm` renders.
- */
-function collectSecretRefPaths(
-  schema: Record<string, unknown> | null | undefined,
-): Set<string> {
-  const paths = new Set<string>();
-  if (!schema || typeof schema !== "object") return paths;
-
-  function walk(node: Record<string, unknown>, prefix: string): void {
-    const props = node.properties as Record<string, Record<string, unknown>> | undefined;
-    if (!props || typeof props !== "object") return;
-    for (const [key, propSchema] of Object.entries(props)) {
-      if (!propSchema || typeof propSchema !== "object") continue;
-      const path = prefix ? `${prefix}.${key}` : key;
-      if (propSchema.format === "secret-ref") {
-        paths.add(path);
-      }
-      // Recurse into nested object schemas
-      if (propSchema.type === "object") {
-        walk(propSchema, path);
-      }
-    }
-  }
-
-  walk(schema, "");
-  return paths;
-}
-
 /**
  * Extract secret reference UUIDs from a plugin's configJson, scoped to only
  * the fields annotated with `format: "secret-ref"` in the schema.
@@ -131,13 +94,8 @@ export function extractSecretRefsFromConfig(
   // If schema declares secret-ref paths, extract only those values.
   if (secretPaths.size > 0) {
     for (const dotPath of secretPaths) {
-      const keys = dotPath.split(".");
+      const current = readConfigValueAtPath(configJson as Record<string, unknown>, dotPath);
-      let current: unknown = configJson;
+      if (typeof current === "string" && isUuidSecretRef(current)) {
-      for (const k of keys) {
-        if (current == null || typeof current !== "object") { current = undefined; break; }
-        current = (current as Record<string, unknown>)[k];
-      }
-      if (typeof current === "string" && isUuid(current)) {
         refs.add(current);
       }
     }
@@ -149,7 +107,7 @@ export function extractSecretRefsFromConfig(
   // instanceConfigSchema.
   function walkAll(value: unknown): void {
     if (typeof value === "string") {
-      if (isUuid(value)) refs.add(value);
+      if (isUuidSecretRef(value)) refs.add(value);
     } else if (Array.isArray(value)) {
       for (const item of value) walkAll(item);
     } else if (value !== null && typeof value === "object") {
@@ -279,7 +237,7 @@ export function createPluginSecretsHandler(
 
       const trimmedRef = secretRef.trim();
 
-      if (!isUuid(trimmedRef)) {
+      if (!isUuidSecretRef(trimmedRef)) {
         throw invalidSecretRef(trimmedRef);
       }
 

server/src/services/sandbox-provider-runtime.ts

@@ -282,15 +282,13 @@ export function findReusableSandboxProviderLeaseId(input: {
 }): string | null {
   const provider = getSandboxProvider(input.config.provider);
   if (!provider) {
-    // For plugin-backed providers, reuse matching is handled by the plugin
-    // environment driver. Fall back to metadata-based matching.
     for (const lease of input.leases) {
       const metadata = lease.metadata ?? {};
       if (
         typeof lease.providerLeaseId === "string" &&
         lease.providerLeaseId.length > 0 &&
         metadata.provider === input.config.provider &&
-        metadata.reuseLease === true
+        metadataMatchesPluginSandboxConfig(input.config, metadata)
       ) {
         return lease.providerLeaseId;
       }
@@ -305,6 +303,21 @@ export function findReusableSandboxProviderLeaseId(input: {
   return null;
 }
 
+function metadataMatchesPluginSandboxConfig(
+  config: SandboxEnvironmentConfig,
+  metadata: Record<string, unknown>,
+): boolean {
+  if (metadata.reuseLease !== true) return false;
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "provider" || key === "reuseLease") continue;
+    if (value === undefined) continue;
+    if (JSON.stringify(metadata[key]) !== JSON.stringify(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export async function probeSandboxProvider(
   config: SandboxEnvironmentConfig,
 ): Promise<EnvironmentProbeResult> {

ui/src/components/AgentConfigForm.tsx

@@ -297,7 +297,12 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
     [adapterType],
   );
   const runnableEnvironments = useMemo(
-    () => environments.filter((environment) => supportedEnvironmentDrivers.has(environment.driver)),
+    () => environments.filter((environment) => {
+      if (!supportedEnvironmentDrivers.has(environment.driver)) return false;
+      if (environment.driver !== "sandbox") return true;
+      const provider = typeof environment.config?.provider === "string" ? environment.config.provider : null;
+      return provider !== null && provider !== "fake";
+    }),
     [environments, supportedEnvironmentDrivers],
   );
 

ui/src/pages/CompanySettings.test.tsx

@@ -164,4 +164,87 @@ describe("CompanySettings", () => {
       root.unmount();
     });
   });
+
+  it("preserves sandbox config when re-selecting the same provider while editing", async () => {
+    const root = createRoot(container);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    mockEnvironmentsApi.list.mockResolvedValue([
+      {
+        id: "env-1",
+        companyId: "company-1",
+        name: "Secure Sandbox",
+        description: null,
+        driver: "sandbox",
+        status: "active",
+        config: {
+          provider: "secure-plugin",
+          template: "saved-template",
+        },
+        metadata: null,
+        createdAt: new Date("2026-04-25T00:00:00.000Z"),
+        updatedAt: new Date("2026-04-25T00:00:00.000Z"),
+      },
+    ]);
+    mockEnvironmentsApi.capabilities.mockResolvedValue(
+      getEnvironmentCapabilities(AGENT_ADAPTER_TYPES, {
+        sandboxProviders: {
+          "secure-plugin": {
+            status: "supported",
+            supportsSavedProbe: true,
+            supportsUnsavedProbe: true,
+            supportsRunExecution: true,
+            supportsReusableLeases: true,
+            displayName: "Secure Sandbox",
+            configSchema: {
+              type: "object",
+              properties: {
+                template: { type: "string", title: "Template" },
+              },
+            },
+          },
+        },
+      }),
+    );
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <TooltipProvider>
+            <CompanySettings />
+          </TooltipProvider>
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+    await flushReact();
+
+    const editButton = Array.from(container.querySelectorAll("button"))
+      .find((button) => button.textContent?.trim() === "Edit");
+    expect(editButton).toBeTruthy();
+
+    await act(async () => {
+      editButton?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flushReact();
+
+    const providerSelect = Array.from(container.querySelectorAll("select"))
+      .find((select) => Array.from(select.options).some((option) => option.value === "secure-plugin")) as HTMLSelectElement | undefined;
+    expect(providerSelect).toBeTruthy();
+
+    await act(async () => {
+      providerSelect!.value = "secure-plugin";
+      providerSelect!.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+    await flushReact();
+
+    const templateInput = Array.from(container.querySelectorAll("input"))
+      .find((input) => (input as HTMLInputElement).value === "saved-template") as HTMLInputElement | undefined;
+    expect(templateInput?.value).toBe("saved-template");
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
 });

ui/src/pages/CompanySettings.tsx

@@ -5,6 +5,7 @@ import {
   getAdapterEnvironmentSupport,
   type Environment,
   type EnvironmentProbeResult,
+  type JsonSchema,
 } from "@paperclipai/shared";
 import { useCompany } from "../context/CompanyContext";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
@@ -19,6 +20,7 @@ import { queryKeys } from "../lib/queryKeys";
 import { Button } from "@/components/ui/button";
 import { Settings, Check, Download, Upload } from "lucide-react";
 import { CompanyPatternIcon } from "../components/CompanyPatternIcon";
+import { JsonSchemaForm, getDefaultValues, validateJsonSchemaForm } from "@/components/JsonSchemaForm";
 import {
   Field,
   ToggleField,
@@ -45,12 +47,7 @@ type EnvironmentFormState = {
   sshKnownHosts: string;
   sshStrictHostKeyChecking: boolean;
   sandboxProvider: string;
-  sandboxImage: string;
+  sandboxConfig: Record<string, unknown>;
-  sandboxTemplate: string;
-  sandboxApiKey: string;
-  sandboxApiKeySecretId: string;
-  sandboxTimeoutMs: string;
-  sandboxReuseLease: boolean;
 };
 
 const ENVIRONMENT_SUPPORT_ROWS = AGENT_ADAPTER_TYPES.map((adapterType) => ({
@@ -81,9 +78,7 @@ function buildEnvironmentPayload(form: EnvironmentFormState) {
         : form.driver === "sandbox"
           ? {
               provider: form.sandboxProvider.trim(),
-              image: form.sandboxImage.trim() || "ubuntu:24.04",
+              ...form.sandboxConfig,
-              timeoutMs: Number.parseInt(form.sandboxTimeoutMs || "300000", 10) || 300000,
-              reuseLease: form.sandboxReuseLease,
             }
           : {},
   } as const;
@@ -103,12 +98,7 @@ function createEmptyEnvironmentForm(): EnvironmentFormState {
     sshKnownHosts: "",
     sshStrictHostKeyChecking: true,
     sandboxProvider: "",
-    sandboxImage: "ubuntu:24.04",
+    sandboxConfig: {},
-    sandboxTemplate: "base",
-    sandboxApiKey: "",
-    sandboxApiKeySecretId: "",
-    sandboxTimeoutMs: "300000",
-    sandboxReuseLease: false,
   };
 }
 
@@ -143,36 +133,31 @@ function readSshConfig(environment: Environment) {
 
 function readSandboxConfig(environment: Environment) {
   const config = environment.config ?? {};
+  const { provider: rawProvider, ...providerConfig } = config;
   return {
-    provider:
+    provider: typeof rawProvider === "string" && rawProvider.trim().length > 0
-      typeof config.provider === "string" && config.provider.trim().length > 0
+      ? rawProvider
-        ? config.provider
         : "fake",
-    image: typeof config.image === "string" && config.image.trim().length > 0
+    config: providerConfig,
-      ? config.image
-      : "ubuntu:24.04",
-    template:
-      typeof config.template === "string" && config.template.trim().length > 0
-        ? config.template
-        : "base",
-    apiKey: "",
-    apiKeySecretId:
-      config.apiKeySecretRef &&
-      typeof config.apiKeySecretRef === "object" &&
-      !Array.isArray(config.apiKeySecretRef) &&
-      typeof (config.apiKeySecretRef as { secretId?: unknown }).secretId === "string"
-        ? String((config.apiKeySecretRef as { secretId: string }).secretId)
-        : "",
-    timeoutMs:
-      typeof config.timeoutMs === "number"
-        ? String(config.timeoutMs)
-        : typeof config.timeoutMs === "string" && config.timeoutMs.trim().length > 0
-          ? config.timeoutMs
-          : "300000",
-    reuseLease: typeof config.reuseLease === "boolean" ? config.reuseLease : false,
   };
 }
 
+function normalizeJsonSchema(schema: unknown): JsonSchema | null {
+  return schema && typeof schema === "object" && !Array.isArray(schema)
+    ? schema as JsonSchema
+    : null;
+}
+
+function summarizeSandboxConfig(config: Record<string, unknown>): string | null {
+  for (const key of ["template", "image", "region", "workspacePath"]) {
+    const value = config[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return null;
+}
+
 function SupportMark({ supported }: { supported: boolean }) {
   return supported ? (
     <span className="inline-flex items-center gap-1 text-green-700 dark:text-green-400">
@@ -525,12 +510,7 @@ export function CompanySettings() {
         description: environment.description ?? "",
         driver: "sandbox",
         sandboxProvider: sandbox.provider,
-        sandboxImage: sandbox.image,
+        sandboxConfig: sandbox.config,
-        sandboxTemplate: sandbox.template,
-        sandboxApiKey: sandbox.apiKey,
-        sandboxApiKeySecretId: sandbox.apiKeySecretId,
-        sandboxTimeoutMs: sandbox.timeoutMs,
-        sandboxReuseLease: sandbox.reuseLease,
       });
       return;
     }
@@ -553,6 +533,8 @@ export function CompanySettings() {
     .map(([provider, capability]) => ({
       provider,
       displayName: capability.displayName || provider,
+      description: capability.description,
+      configSchema: normalizeJsonSchema(capability.configSchema),
     }))
     .sort((left, right) => left.displayName.localeCompare(right.displayName));
   const sandboxCreationEnabled = discoveredPluginSandboxProviders.length > 0;
@@ -563,21 +545,32 @@ export function CompanySettings() {
     !discoveredPluginSandboxProviders.some((provider) => provider.provider === environmentForm.sandboxProvider)
       ? [
           ...discoveredPluginSandboxProviders,
-          { provider: environmentForm.sandboxProvider, displayName: environmentForm.sandboxProvider },
+          { provider: environmentForm.sandboxProvider, displayName: environmentForm.sandboxProvider, description: undefined, configSchema: null },
         ]
       : discoveredPluginSandboxProviders;
 
+  const selectedSandboxProvider = pluginSandboxProviders.find(
+    (provider) => provider.provider === environmentForm.sandboxProvider,
+  ) ?? null;
+  const selectedSandboxSchema = selectedSandboxProvider?.configSchema ?? null;
+  const sandboxConfigErrors =
+    environmentForm.driver === "sandbox" && selectedSandboxSchema
+      ? validateJsonSchemaForm(selectedSandboxSchema as any, environmentForm.sandboxConfig)
+      : {};
+
   useEffect(() => {
     if (environmentForm.driver !== "sandbox") return;
     if (environmentForm.sandboxProvider.trim().length > 0 && environmentForm.sandboxProvider !== "fake") return;
     const firstProvider = discoveredPluginSandboxProviders[0]?.provider;
     if (!firstProvider) return;
+    const firstSchema = discoveredPluginSandboxProviders[0]?.configSchema;
     setEnvironmentForm((current) => (
       current.driver !== "sandbox" || (current.sandboxProvider.trim().length > 0 && current.sandboxProvider !== "fake")
         ? current
         : {
             ...current,
             sandboxProvider: firstProvider,
+            sandboxConfig: firstSchema ? getDefaultValues(firstSchema as any) : {},
           }
     ));
   }, [discoveredPluginSandboxProviders, environmentForm.driver, environmentForm.sandboxProvider]);
@@ -593,10 +586,7 @@ export function CompanySettings() {
     (environmentForm.driver !== "sandbox" ||
       environmentForm.sandboxProvider.trim().length > 0 &&
       environmentForm.sandboxProvider !== "fake" &&
-      environmentForm.sandboxImage.trim().length > 0 &&
+      Object.keys(sandboxConfigErrors).length === 0);
-      environmentForm.sandboxTimeoutMs.trim().length > 0 &&
-      Number.isFinite(Number(environmentForm.sandboxTimeoutMs)) &&
-      Number(environmentForm.sandboxTimeoutMs) > 0);
 
   return (
     <div className="max-w-2xl space-y-6">
@@ -835,10 +825,14 @@ export function CompanySettings() {
                           </div>
                         ) : environment.driver === "sandbox" ? (
                           <div className="text-xs text-muted-foreground">
-                            {String(environment.config.provider ?? "fake")} sandbox provider ·{" "}
+                            {(() => {
-                            {typeof environment.config.image === "string"
+                              const provider =
-                              ? environment.config.image
+                                typeof environment.config.provider === "string" ? environment.config.provider : "sandbox";
-                              : "ubuntu:24.04"}
+                              const displayName =
+                                environmentCapabilities?.sandboxProviders?.[provider]?.displayName ?? provider;
+                              const summary = summarizeSandboxConfig(environment.config as Record<string, unknown>);
+                              return `${displayName} sandbox provider${summary ? ` · ${summary}` : ""}`;
+                            })()}
                           </div>
                         ) : (
                           <div className="text-xs text-muted-foreground">Runs on this Paperclip host.</div>
@@ -920,6 +914,16 @@ export function CompanySettings() {
                         e.target.value === "sandbox"
                           ? current.sandboxProvider.trim() || discoveredPluginSandboxProviders[0]?.provider || ""
                           : current.sandboxProvider,
+                      sandboxConfig:
+                        e.target.value === "sandbox"
+                          ? (
+                              current.sandboxProvider.trim().length > 0 && current.driver === "sandbox"
+                                ? current.sandboxConfig
+                                : discoveredPluginSandboxProviders[0]?.configSchema
+                                  ? getDefaultValues(discoveredPluginSandboxProviders[0].configSchema as any)
+                                  : {}
+                            )
+                          : current.sandboxConfig,
                       driver:
                         e.target.value === "local"
                           ? "local"
@@ -1024,11 +1028,20 @@ export function CompanySettings() {
                     <select
                       className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
                       value={environmentForm.sandboxProvider}
-                      onChange={(e) =>
+                      onChange={(e) => {
+                        const nextProviderKey = e.target.value;
+                        const nextProvider = pluginSandboxProviders.find((provider) => provider.provider === nextProviderKey) ?? null;
                         setEnvironmentForm((current) => ({
                           ...current,
-                          sandboxProvider: e.target.value,
+                          sandboxProvider: nextProviderKey,
-                        }))}
+                          sandboxConfig:
+                            current.sandboxProvider === nextProviderKey
+                              ? current.sandboxConfig
+                              : nextProvider?.configSchema
+                                ? getDefaultValues(nextProvider.configSchema as any)
+                                : {},
+                        }));
+                      }}
                     >
                       {pluginSandboxProviders.map((provider) => (
                         <option key={provider.provider} value={provider.provider}>
@@ -1037,33 +1050,25 @@ export function CompanySettings() {
                       ))}
                     </select>
                   </Field>
-                  <Field label="Image" hint="Operator-facing sandbox image label passed through to the selected provider plugin.">
+                  <div className="md:col-span-2 space-y-3">
-                    <input
+                    {selectedSandboxProvider?.description ? (
-                      className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+                      <div className="text-xs text-muted-foreground">
-                      type="text"
+                        {selectedSandboxProvider.description}
-                      placeholder="ubuntu:24.04"
+                      </div>
-                      value={environmentForm.sandboxImage}
+                    ) : null}
-                      onChange={(e) => setEnvironmentForm((current) => ({ ...current, sandboxImage: e.target.value }))}
+                    {selectedSandboxSchema ? (
-                    />
+                      <JsonSchemaForm
-                  </Field>
+                        schema={selectedSandboxSchema as any}
-                  <Field label="Timeout (ms)" hint="Command timeout passed to the sandbox provider plugin.">
+                        values={environmentForm.sandboxConfig}
-                    <input
+                        onChange={(values) =>
-                      className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+                          setEnvironmentForm((current) => ({ ...current, sandboxConfig: values }))}
-                      type="number"
+                        errors={sandboxConfigErrors}
-                      min={1}
-                      value={environmentForm.sandboxTimeoutMs}
-                      onChange={(e) =>
-                        setEnvironmentForm((current) => ({ ...current, sandboxTimeoutMs: e.target.value }))}
-                    />
-                  </Field>
-                  <div className="md:col-span-2">
-                    <ToggleField
-                      label="Reuse lease"
-                      hint="When enabled, Paperclip will try to reconnect to a previously leased sandbox before provisioning a new one."
-                      checked={environmentForm.sandboxReuseLease}
-                      onChange={(checked) =>
-                        setEnvironmentForm((current) => ({ ...current, sandboxReuseLease: checked }))}
                       />
+                    ) : (
+                      <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.
+                      </div>
+                    )}
                   </div>
                 </div>
               ) : null}