Add sandbox environment support (#4415)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The environment/runtime layer decides where agent work executes and
how the control plane reaches those runtimes.
> - Today Paperclip can run locally and over SSH, but sandboxed
execution needs a first-class environment model instead of one-off
adapter behavior.
> - We also want sandbox providers to be pluggable so the core does not
hardcode every provider implementation.
> - This branch adds the Sandbox environment path, the provider
contract, and a deterministic fake provider plugin.
> - That required synchronized changes across shared contracts, plugin
SDK surfaces, server runtime orchestration, and the UI
environment/workspace flows.
> - The result is that sandbox execution becomes a core control-plane
capability while keeping provider implementations extensible and
testable.

## What Changed

- Added sandbox runtime support to the environment execution path,
including runtime URL discovery, sandbox execution targeting,
orchestration, and heartbeat integration.
- Added plugin-provider support for sandbox environments so providers
can be supplied via plugins instead of hardcoded server logic.
- Added the fake sandbox provider plugin with deterministic behavior
suitable for local and automated testing.
- Updated shared types, validators, plugin protocol definitions, and SDK
helpers to carry sandbox provider and workspace-runtime contracts across
package boundaries.
- Updated server routes and services so companies can create sandbox
environments, select them for work, and execute work through the sandbox
runtime path.
- Updated the UI environment and workspace surfaces to expose sandbox
environment configuration and selection.
- Added test coverage for sandbox runtime behavior, provider seams,
environment route guards, orchestration, and the fake provider plugin.

## Verification

- Ran locally before the final fixture-only scrub:
  - `pnpm -r typecheck`
  - `pnpm test:run`
  - `pnpm build`
- Ran locally after the final scrub amend:
  - `pnpm vitest run server/src/__tests__/runtime-api.test.ts`
- Reviewer spot checks:
  - create a sandbox environment backed by the fake provider plugin
  - run work through that environment
- confirm sandbox provider execution does not inherit host secrets
implicitly

## Risks

- This touches shared contracts, plugin SDK plumbing, server runtime
orchestration, and UI environment/workspace flows, so regressions would
likely show up as cross-layer mismatches rather than isolated type
errors.
- Runtime URL discovery and sandbox callback selection are sensitive to
host/bind configuration; if that logic is wrong, sandbox-backed
callbacks may fail even when execution succeeds.
- The fake provider plugin is intentionally deterministic and
test-oriented; future providers may expose capability gaps that this
branch does not yet cover.

## Model Used

- OpenAI Codex coding agent on a GPT-5-class backend in the
Paperclip/Codex harness. Exact backend model ID is not exposed
in-session. Tool-assisted workflow with shell execution, file editing,
git history inspection, and local test execution.

## 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/constants.ts

@@ -218,16 +218,21 @@ export const PROJECT_STATUSES = [
 ] as const;
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
 
-export const ENVIRONMENT_DRIVERS = ["local", "ssh"] as const;
+export const ENVIRONMENT_DRIVERS = ["local", "ssh", "sandbox", "plugin"] as const;
 export type EnvironmentDriver = (typeof ENVIRONMENT_DRIVERS)[number];
 
 export const ENVIRONMENT_STATUSES = ["active", "archived"] as const;
 export type EnvironmentStatus = (typeof ENVIRONMENT_STATUSES)[number];
 
-export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed"] as const;
+export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed", "retained"] as const;
 export type EnvironmentLeaseStatus = (typeof ENVIRONMENT_LEASE_STATUSES)[number];
 
-export const ENVIRONMENT_LEASE_POLICIES = ["ephemeral"] as const;
+export const ENVIRONMENT_LEASE_POLICIES = [
+  "ephemeral",
+  "reuse_by_environment",
+  "reuse_by_execution_workspace",
+  "retain_on_failure",
+] as const;
 export type EnvironmentLeasePolicy = (typeof ENVIRONMENT_LEASE_POLICIES)[number];
 
 export const ENVIRONMENT_LEASE_CLEANUP_STATUSES = ["pending", "success", "failed"] as const;
@@ -480,13 +485,13 @@ export type JoinRequestStatus = (typeof JOIN_REQUEST_STATUSES)[number];
 
 export const PERMISSION_KEYS = [
   "agents:create",
+  "environments:manage",
   "users:invite",
   "users:manage_permissions",
   "tasks:assign",
   "tasks:assign_scope",
   "tasks:manage_active_checkouts",
   "joins:approve",
-  "environments:manage",
 ] as const;
 export type PermissionKey = (typeof PERMISSION_KEYS)[number];
 
@@ -598,6 +603,7 @@ export const PLUGIN_CAPABILITIES = [
   "api.routes.register",
   "http.outbound",
   "secrets.read-ref",
+  "environment.drivers.register",
   // Agent Tools
   "agent.tools.register",
   // UI

packages/shared/src/environment-support.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { isSandboxProviderSupportedForAdapter } from "./environment-support.js";
+
+describe("isSandboxProviderSupportedForAdapter", () => {
+  it("accepts additional sandbox providers for remote-managed adapters", () => {
+    expect(
+      isSandboxProviderSupportedForAdapter("codex_local", "fake-plugin", ["fake-plugin"]),
+    ).toBe(true);
+  });
+
+  it("rejects providers for adapters without remote-managed environment support", () => {
+    expect(
+      isSandboxProviderSupportedForAdapter("openclaw", "fake-plugin", ["fake-plugin"]),
+    ).toBe(false);
+  });
+});

packages/shared/src/environment-support.ts

@@ -1,15 +1,31 @@
 import type { AgentAdapterType, EnvironmentDriver } from "./constants.js";
+import type { SandboxEnvironmentProvider } from "./types/environment.js";
 
 export type EnvironmentSupportStatus = "supported" | "unsupported";
 
 export interface AdapterEnvironmentSupport {
   adapterType: AgentAdapterType;
   drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;
+  sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentSupportStatus>;
+}
+
+export interface EnvironmentProviderCapability {
+  status: EnvironmentSupportStatus;
+  supportsSavedProbe: boolean;
+  supportsUnsavedProbe: boolean;
+  supportsRunExecution: boolean;
+  supportsReusableLeases: boolean;
+  displayName?: string;
+  description?: string;
+  source?: "builtin" | "plugin";
+  pluginKey?: string;
+  pluginId?: string;
 }
 
 export interface EnvironmentCapabilities {
   adapters: AdapterEnvironmentSupport[];
   drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;
+  sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentProviderCapability>;
 }
 
 const REMOTE_MANAGED_ADAPTERS = new Set<AgentAdapterType>([
@@ -27,10 +43,19 @@ export function adapterSupportsRemoteManagedEnvironments(adapterType: string): b
 
 export function supportedEnvironmentDriversForAdapter(adapterType: string): EnvironmentDriver[] {
   return adapterSupportsRemoteManagedEnvironments(adapterType)
-    ? ["local", "ssh"]
+    ? ["local", "ssh", "sandbox"]
     : ["local"];
 }
 
+export function supportedSandboxProvidersForAdapter(
+  adapterType: string,
+  additionalProviders: readonly string[] = [],
+): SandboxEnvironmentProvider[] {
+  return adapterSupportsRemoteManagedEnvironments(adapterType)
+    ? Array.from(new Set(additionalProviders)) as SandboxEnvironmentProvider[]
+    : [];
+}
+
 export function isEnvironmentDriverSupportedForAdapter(
   adapterType: string,
   driver: string,
@@ -38,27 +63,83 @@ export function isEnvironmentDriverSupportedForAdapter(
   return supportedEnvironmentDriversForAdapter(adapterType).includes(driver as EnvironmentDriver);
 }
 
+export function isSandboxProviderSupportedForAdapter(
+  adapterType: string,
+  provider: string | null | undefined,
+  additionalProviders: readonly string[] = [],
+): boolean {
+  if (!provider) return false;
+  return supportedSandboxProvidersForAdapter(adapterType, additionalProviders).includes(
+    provider as SandboxEnvironmentProvider,
+  );
+}
+
 export function getAdapterEnvironmentSupport(
   adapterType: AgentAdapterType,
+  additionalSandboxProviders: readonly string[] = [],
 ): AdapterEnvironmentSupport {
   const supportedDrivers = new Set(supportedEnvironmentDriversForAdapter(adapterType));
+  const supportedProviders = new Set(supportedSandboxProvidersForAdapter(adapterType, additionalSandboxProviders));
+  const sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentSupportStatus> = {
+    fake: supportedProviders.has("fake") ? "supported" : "unsupported",
+  };
+  for (const provider of additionalSandboxProviders) {
+    sandboxProviders[provider as SandboxEnvironmentProvider] = supportedProviders.has(provider as SandboxEnvironmentProvider)
+      ? "supported"
+      : "unsupported";
+  }
   return {
     adapterType,
     drivers: {
       local: supportedDrivers.has("local") ? "supported" : "unsupported",
       ssh: supportedDrivers.has("ssh") ? "supported" : "unsupported",
+      sandbox: supportedDrivers.has("sandbox") ? "supported" : "unsupported",
+      plugin: supportedDrivers.has("plugin") ? "supported" : "unsupported",
     },
+    sandboxProviders,
   };
 }
 
 export function getEnvironmentCapabilities(
   adapterTypes: readonly AgentAdapterType[],
+  options: {
+    sandboxProviders?: Record<string, Partial<EnvironmentProviderCapability>>;
+  } = {},
 ): EnvironmentCapabilities {
+  const pluginProviderKeys = Object.keys(options.sandboxProviders ?? {});
+  const sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentProviderCapability> = {
+    fake: {
+      status: "unsupported",
+      supportsSavedProbe: true,
+      supportsUnsavedProbe: true,
+      supportsRunExecution: false,
+      supportsReusableLeases: true,
+      displayName: "Fake",
+      source: "builtin",
+    },
+  };
+  for (const [provider, capability] of Object.entries(options.sandboxProviders ?? {})) {
+    sandboxProviders[provider as SandboxEnvironmentProvider] = {
+      status: capability.status ?? "supported",
+      supportsSavedProbe: capability.supportsSavedProbe ?? true,
+      supportsUnsavedProbe: capability.supportsUnsavedProbe ?? true,
+      supportsRunExecution: capability.supportsRunExecution ?? true,
+      supportsReusableLeases: capability.supportsReusableLeases ?? true,
+      displayName: capability.displayName,
+      description: capability.description,
+      source: capability.source ?? "plugin",
+      pluginKey: capability.pluginKey,
+      pluginId: capability.pluginId,
+    };
+  }
   return {
-    adapters: adapterTypes.map((adapterType) => getAdapterEnvironmentSupport(adapterType)),
+    adapters: adapterTypes.map((adapterType) => getAdapterEnvironmentSupport(adapterType, pluginProviderKeys)),
     drivers: {
       local: "supported",
       ssh: "supported",
+      sandbox: "supported",
+      plugin: "unsupported",
     },
+    sandboxProviders,
   };
 }

packages/shared/src/index.ts

@@ -219,7 +219,12 @@ export type {
   Environment,
   EnvironmentLease,
   EnvironmentProbeResult,
+  FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
+  PluginEnvironmentConfig,
+  SandboxEnvironmentConfig,
+  SandboxEnvironmentProvider,
   SshEnvironmentConfig,
   FeedbackVote,
   FeedbackDataSharingPreference,
@@ -300,6 +305,10 @@ export type {
   WorkspaceOperationPhase,
   WorkspaceOperationStatus,
   WorkspaceRuntimeDesiredState,
+  WorkspaceRealizationRecord,
+  WorkspaceRealizationRequest,
+  WorkspaceRealizationSyncStrategy,
+  WorkspaceRealizationTransport,
   ExecutionWorkspaceStrategyType,
   ExecutionWorkspaceMode,
   ExecutionWorkspaceProviderType,
@@ -471,6 +480,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginLauncherActionDeclaration,
   PluginLauncherRenderDeclaration,
@@ -542,17 +552,6 @@ export {
   isClosedIsolatedExecutionWorkspace,
 } from "./execution-workspace-guards.js";
 
-export {
-  adapterSupportsRemoteManagedEnvironments,
-  getAdapterEnvironmentSupport,
-  getEnvironmentCapabilities,
-  isEnvironmentDriverSupportedForAdapter,
-  supportedEnvironmentDriversForAdapter,
-  type AdapterEnvironmentSupport,
-  type EnvironmentCapabilities,
-  type EnvironmentSupportStatus,
-} from "./environment-support.js";
-
 export {
   instanceGeneralSettingsSchema,
   patchInstanceGeneralSettingsSchema,
@@ -824,6 +823,7 @@ export {
   pluginJobDeclarationSchema,
   pluginWebhookDeclarationSchema,
   pluginToolDeclarationSchema,
+  pluginEnvironmentDriverDeclarationSchema,
   pluginUiSlotDeclarationSchema,
   pluginLauncherActionDeclarationSchema,
   pluginLauncherRenderDeclarationSchema,
@@ -842,6 +842,7 @@ export {
   type PluginJobDeclarationInput,
   type PluginWebhookDeclarationInput,
   type PluginToolDeclarationInput,
+  type PluginEnvironmentDriverDeclarationInput,
   type PluginUiSlotDeclarationInput,
   type PluginLauncherActionDeclarationInput,
   type PluginLauncherRenderDeclarationInput,
@@ -926,3 +927,20 @@ export {
   type SecretsLocalEncryptedConfig,
   type ConfigMeta,
 } from "./config-schema.js";
+
+export {
+  adapterSupportsRemoteManagedEnvironments,
+  getEnvironmentCapabilities,
+  getAdapterEnvironmentSupport,
+  isEnvironmentDriverSupportedForAdapter,
+  isSandboxProviderSupportedForAdapter,
+  supportedEnvironmentDriversForAdapter,
+  supportedSandboxProvidersForAdapter,
+} from "./environment-support.js";
+
+export type {
+  AdapterEnvironmentSupport,
+  EnvironmentCapabilities,
+  EnvironmentProviderCapability,
+  EnvironmentSupportStatus,
+} from "./environment-support.js";

packages/shared/src/types/environment.ts

@@ -22,6 +22,41 @@ 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 {
+  provider: "fake";
+  image: string;
+  reuseLease: boolean;
+}
+
+export interface PluginSandboxEnvironmentConfig {
+  provider: SandboxEnvironmentProvider;
+  reuseLease: boolean;
+  timeoutMs?: number;
+  [key: string]: unknown;
+}
+
+export type SandboxEnvironmentConfig =
+  | FakeSandboxEnvironmentConfig
+  | PluginSandboxEnvironmentConfig;
+
+export interface PluginEnvironmentConfig {
+  pluginKey: string;
+  driverKey: string;
+  driverConfig: Record<string, unknown>;
+}
+
 export interface EnvironmentProbeResult {
   ok: boolean;
   driver: EnvironmentDriver;

packages/shared/src/types/index.ts

@@ -3,7 +3,12 @@ export type {
   Environment,
   EnvironmentLease,
   EnvironmentProbeResult,
+  FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
+  PluginEnvironmentConfig,
+  SandboxEnvironmentConfig,
+  SandboxEnvironmentProvider,
   SshEnvironmentConfig,
 } from "./environment.js";
 export type {
@@ -85,6 +90,10 @@ export type {
   WorkspaceRuntimeService,
   WorkspaceRuntimeServiceStateMap,
   WorkspaceRuntimeDesiredState,
+  WorkspaceRealizationRecord,
+  WorkspaceRealizationRequest,
+  WorkspaceRealizationSyncStrategy,
+  WorkspaceRealizationTransport,
   ExecutionWorkspaceStrategyType,
   ExecutionWorkspaceMode,
   ExecutionWorkspaceProviderType,
@@ -281,6 +290,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginLauncherActionDeclaration,
   PluginLauncherRenderDeclaration,

packages/shared/src/types/plugin.ts

@@ -89,6 +89,30 @@ export interface PluginToolDeclaration {
   parametersSchema: JsonSchema;
 }
 
+/**
+ * Declares an environment runtime driver contributed by the plugin.
+ *
+ * Requires the `environment.drivers.register` capability.
+ */
+export interface PluginEnvironmentDriverDeclaration {
+  /** Stable driver key, unique within the plugin. Namespaced by plugin ID at runtime. */
+  driverKey: string;
+  /**
+   * Driver classification.
+   *
+   * `environment_driver` is used by core `driver: "plugin"` environments.
+   * `sandbox_provider` is used by core `driver: "sandbox"` environments whose
+   * provider key is implemented by a plugin.
+   */
+  kind?: "environment_driver" | "sandbox_provider";
+  /** Human-readable name shown in environment configuration UI. */
+  displayName: string;
+  /** Optional description for operator-facing docs or UI affordances. */
+  description?: string;
+  /** JSON Schema describing the driver's provider-specific configuration. */
+  configSchema: JsonSchema;
+}
+
 /**
  * Declares a UI extension slot the plugin fills with a React component.
  *
@@ -296,6 +320,8 @@ export interface PaperclipPluginManifestV1 {
   database?: PluginDatabaseDeclaration;
   /** Scoped JSON API routes mounted under `/api/plugins/:pluginId/api/*`. */
   apiRoutes?: PluginApiRouteDeclaration[];
+  /** Environment drivers this plugin contributes. Requires `environment.drivers.register` capability. */
+  environmentDrivers?: PluginEnvironmentDriverDeclaration[];
   /**
    * Legacy top-level launcher declarations.
    * Prefer `ui.launchers` for new manifests.

packages/shared/src/types/workspace-runtime.ts

@@ -231,11 +231,13 @@ export interface WorkspaceRuntimeService {
   updatedAt: Date;
 }
 
-export type WorkspaceRealizationTransport = "local" | "ssh";
+export type WorkspaceRealizationTransport = "local" | "ssh" | "sandbox" | "plugin";
 
 export type WorkspaceRealizationSyncStrategy =
   | "none"
-  | "ssh_git_import_export";
+  | "ssh_git_import_export"
+  | "sandbox_archive_upload_download"
+  | "provider_defined";
 
 export interface WorkspaceRealizationRequest {
   version: 1;
@@ -288,6 +290,7 @@ export interface WorkspaceRealizationRecord {
     host?: string | null;
     port?: number | null;
     username?: string | null;
+    sandboxId?: string | null;
   };
   sync: {
     strategy: WorkspaceRealizationSyncStrategy;

packages/shared/src/validators/index.ts

@@ -344,6 +344,7 @@ export {
   pluginJobDeclarationSchema,
   pluginWebhookDeclarationSchema,
   pluginToolDeclarationSchema,
+  pluginEnvironmentDriverDeclarationSchema,
   pluginUiSlotDeclarationSchema,
   pluginLauncherActionDeclarationSchema,
   pluginLauncherRenderDeclarationSchema,
@@ -362,6 +363,7 @@ export {
   type PluginJobDeclarationInput,
   type PluginWebhookDeclarationInput,
   type PluginToolDeclarationInput,
+  type PluginEnvironmentDriverDeclarationInput,
   type PluginUiSlotDeclarationInput,
   type PluginLauncherActionDeclarationInput,
   type PluginLauncherRenderDeclarationInput,

packages/shared/src/validators/plugin.ts

@@ -107,6 +107,21 @@ export const pluginToolDeclarationSchema = z.object({
   parametersSchema: jsonSchemaSchema,
 });
 
+export const pluginEnvironmentDriverDeclarationSchema = z.object({
+  driverKey: z.string().min(1).regex(
+    /^[a-z0-9][a-z0-9._-]*$/,
+    "Environment driver key must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, hyphens, or underscores",
+  ),
+  kind: z.enum(["environment_driver", "sandbox_provider"]).optional(),
+  displayName: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  configSchema: jsonSchemaSchema,
+});
+
+export type PluginEnvironmentDriverDeclarationInput = z.infer<
+  typeof pluginEnvironmentDriverDeclarationSchema
+>;
+
 export type PluginToolDeclarationInput = z.infer<typeof pluginToolDeclarationSchema>;
 
 /**
@@ -410,11 +425,13 @@ export type PluginApiRouteDeclarationInput = z.infer<typeof pluginApiRouteDeclar
  * Cross-field rules enforced via `superRefine`:
  * - `entrypoints.ui` required when `ui.slots` declared
  * - `agent.tools.register` capability required when `tools` declared
+ * - `environment.drivers.register` capability required when `environmentDrivers` declared
  * - `jobs.schedule` capability required when `jobs` declared
  * - `webhooks.receive` capability required when `webhooks` declared
  * - duplicate `jobs[].jobKey` values are rejected
  * - duplicate `webhooks[].endpointKey` values are rejected
  * - duplicate `tools[].name` values are rejected
+ * - duplicate `environmentDrivers[].driverKey` values are rejected
  * - duplicate `ui.slots[].id` values are rejected
  *
  * @see PLUGIN_SPEC.md §10.1 — Manifest shape
@@ -453,6 +470,7 @@ export const pluginManifestV1Schema = z.object({
   tools: z.array(pluginToolDeclarationSchema).optional(),
   database: pluginDatabaseDeclarationSchema.optional(),
   apiRoutes: z.array(pluginApiRouteDeclarationSchema).optional(),
+  environmentDrivers: z.array(pluginEnvironmentDriverDeclarationSchema).optional(),
   launchers: z.array(pluginLauncherDeclarationSchema).optional(),
   ui: z.object({
     slots: z.array(pluginUiSlotDeclarationSchema).min(1).optional(),
@@ -500,6 +518,17 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  // environment drivers require environment.drivers.register
+  if (manifest.environmentDrivers && manifest.environmentDrivers.length > 0) {
+    if (!manifest.capabilities.includes("environment.drivers.register")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Capability 'environment.drivers.register' is required when environmentDrivers are declared",
+        path: ["capabilities"],
+      });
+    }
+  }
+
   // jobs require jobs.schedule (PLUGIN_SPEC.md §17)
   if (manifest.jobs && manifest.jobs.length > 0) {
     if (!manifest.capabilities.includes("jobs.schedule")) {
@@ -622,6 +651,19 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  // environment driver keys must be unique within the plugin
+  if (manifest.environmentDrivers) {
+    const driverKeys = manifest.environmentDrivers.map((d) => d.driverKey);
+    const duplicates = driverKeys.filter((key, i) => driverKeys.indexOf(key) !== i);
+    if (duplicates.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate environment driver keys: ${[...new Set(duplicates)].join(", ")}`,
+        path: ["environmentDrivers"],
+      });
+    }
+  }
+
   // UI slot ids must be unique within the plugin (namespaced at runtime)
   if (manifest.ui) {
     if (manifest.ui.slots) {