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

server/src/services/environment-config.ts

@@ -1,15 +1,21 @@
-import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 import type { Db } from "@paperclipai/db";
 import type {
   Environment,
   EnvironmentDriver,
+  FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
+  PluginEnvironmentConfig,
+  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 type { PluginWorkerManager } from "./plugin-worker-manager.js";
 
 const secretRefSchema = z.object({
   type: z.literal("secret_ref"),
@@ -37,6 +43,80 @@ const sshEnvironmentConfigSchema = z.object({
   strictHostKeyChecking: z.boolean().optional().default(true),
 }).strict();
 
+const fakeSandboxEnvironmentConfigSchema = z.object({
+  provider: z.literal("fake").default("fake"),
+  image: z
+    .string()
+    .trim()
+    .min(1, "Fake sandbox environments require an image.")
+    .default("ubuntu:24.04"),
+  reuseLease: z.boolean().optional().default(false),
+}).strict();
+
+const pluginSandboxProviderKeySchema = z.string()
+  .trim()
+  .min(1, "Sandbox provider is required.")
+  .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,
+  timeoutMs: z.coerce.number().int().min(1).max(86_400_000).optional(),
+  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(
+    /^[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",
+  ),
+  driverConfig: z.record(z.unknown()).optional().default({}),
+}).strict();
+
+export type ParsedEnvironmentConfig =
+  | { driver: "local"; config: LocalEnvironmentConfig }
+  | { driver: "ssh"; config: SshEnvironmentConfig }
+  | { driver: "sandbox"; config: SandboxEnvironmentConfig }
+  | { driver: "plugin"; config: PluginEnvironmentConfig };
+
+function toErrorMessage(error: z.ZodError) {
+  const first = error.issues[0];
+  if (!first) return "Invalid environment config.";
+  return first.message;
+}
+
+function getSandboxProvider(raw: Record<string, unknown>) {
+  return typeof raw.provider === "string" && raw.provider.trim().length > 0 ? raw.provider.trim() : "fake";
+}
+
+function parseSandboxEnvironmentConfig(
+  input: Record<string, unknown> | null | undefined,
+  mode: SandboxConfigSchemaMode,
+) {
+  const raw = parseObject(input);
+  const provider = getSandboxProvider(raw);
+
+  if (provider === "fake") {
+    const parsed = fakeSandboxEnvironmentConfigSchema.safeParse(raw);
+    return parsed.success
+      ? ({ success: true as const, data: parsed.data satisfies FakeSandboxEnvironmentConfig })
+      : ({ success: false as const, error: parsed.error });
+  }
+
+  const parsed = pluginSandboxEnvironmentConfigSchema.safeParse(raw);
+  return parsed.success
+    ? ({ success: true as const, data: parsed.data satisfies PluginSandboxEnvironmentConfig })
+    : ({ success: false as const, error: parsed.error });
+}
+
 const sshEnvironmentConfigProbeSchema = sshEnvironmentConfigSchema.extend({
   privateKey: z
     .string()
@@ -48,16 +128,6 @@ const sshEnvironmentConfigProbeSchema = sshEnvironmentConfigSchema.extend({
 
 const sshEnvironmentConfigPersistenceSchema = sshEnvironmentConfigProbeSchema;
 
-export type ParsedEnvironmentConfig =
-  | { driver: "local"; config: LocalEnvironmentConfig }
-  | { driver: "ssh"; config: SshEnvironmentConfig };
-
-function toErrorMessage(error: z.ZodError) {
-  const first = error.issues[0];
-  if (!first) return "Invalid environment config.";
-  return first.message;
-}
-
 function secretName(input: {
   environmentName: string;
   driver: EnvironmentDriver;
@@ -115,6 +185,26 @@ export function normalizeEnvironmentConfig(input: {
     return parsed.data satisfies SshEnvironmentConfig;
   }
 
+  if (input.driver === "sandbox") {
+    const parsed = parseSandboxEnvironmentConfig(input.config, "stored");
+    if (!parsed.success) {
+      throw unprocessable(toErrorMessage(parsed.error), {
+        issues: parsed.error.issues,
+      });
+    }
+    return parsed.data;
+  }
+
+  if (input.driver === "plugin") {
+    const parsed = pluginEnvironmentConfigSchema.safeParse(parseObject(input.config));
+    if (!parsed.success) {
+      throw unprocessable(toErrorMessage(parsed.error), {
+        issues: parsed.error.issues,
+      });
+    }
+    return parsed.data satisfies PluginEnvironmentConfig;
+  }
+
   throw unprocessable(`Unsupported environment driver "${input.driver}".`);
 }
 
@@ -132,6 +222,16 @@ export function normalizeEnvironmentConfigForProbe(input: {
     return parsed.data satisfies SshEnvironmentConfig;
   }
 
+  if (input.driver === "sandbox") {
+    const parsed = parseSandboxEnvironmentConfig(input.config, "probe");
+    if (!parsed.success) {
+      throw unprocessable(toErrorMessage(parsed.error), {
+        issues: parsed.error.issues,
+      });
+    }
+    return parsed.data;
+  }
+
   return normalizeEnvironmentConfig(input);
 }
 
@@ -142,6 +242,7 @@ export async function normalizeEnvironmentConfigForPersistence(input: {
   driver: EnvironmentDriver;
   config: Record<string, unknown> | null | undefined;
   actor?: { userId?: string | null; agentId?: string | null };
+  pluginWorkerManager?: PluginWorkerManager;
 }): Promise<Record<string, unknown>> {
   if (input.driver === "ssh") {
     const parsed = sshEnvironmentConfigPersistenceSchema.safeParse(parseObject(input.config));
@@ -177,6 +278,39 @@ export async function normalizeEnvironmentConfigForPersistence(input: {
     } satisfies SshEnvironmentConfig;
   }
 
+  if (input.driver === "sandbox") {
+    const parsed = parseSandboxEnvironmentConfig(input.config, "persistence");
+    if (!parsed.success) {
+      throw unprocessable(toErrorMessage(parsed.error), {
+        issues: parsed.error.issues,
+      });
+    }
+    const sandboxConfig = parsed.data;
+    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.driver === "plugin") {
+    const parsed = pluginEnvironmentConfigSchema.safeParse(parseObject(input.config));
+    if (!parsed.success) {
+      throw unprocessable(toErrorMessage(parsed.error), {
+        issues: parsed.error.issues,
+      });
+    }
+    if (!input.pluginWorkerManager) {
+      throw unprocessable("Plugin environment config validation requires a running plugin worker manager.");
+    }
+    return { ...(await validatePluginEnvironmentDriverConfig({
+      db: input.db,
+      workerManager: input.pluginWorkerManager,
+      config: parsed.data,
+    })) };
+  }
+
   return normalizeEnvironmentConfig({
     driver: input.driver,
     config: input.config,
@@ -189,12 +323,14 @@ export async function resolveEnvironmentDriverConfigForRuntime(
   environment: Pick<Environment, "driver" | "config">,
 ): Promise<ParsedEnvironmentConfig> {
   const parsed = parseEnvironmentDriverConfig(environment);
+  const secrets = secretService(db);
+
   if (parsed.driver === "ssh" && parsed.config.privateKeySecretRef) {
     return {
       driver: "ssh",
       config: {
         ...parsed.config,
-        privateKey: await secretService(db).resolveSecretValue(
+        privateKey: await secrets.resolveSecretValue(
           companyId,
           parsed.config.privateKeySecretRef.secretId,
           parsed.config.privateKeySecretRef.version ?? "latest",
@@ -233,5 +369,24 @@ export function parseEnvironmentDriverConfig(
     };
   }
 
+  if (environment.driver === "sandbox") {
+    const parsed = parseSandboxEnvironmentConfig(environment.config, "stored");
+    if (!parsed.success) {
+      throw parsed.error;
+    }
+    return {
+      driver: "sandbox",
+      config: parsed.data,
+    };
+  }
+
+  if (environment.driver === "plugin") {
+    const parsed = pluginEnvironmentConfigSchema.parse(parseObject(environment.config));
+    return {
+      driver: "plugin",
+      config: parsed,
+    };
+  }
+
   throw new Error(`Unsupported environment driver "${environment.driver}".`);
 }