Add Modal VM as a distinct sandbox backend

.env.example

@@ -158,6 +158,7 @@ GITLAB_NAMESPACE=
 # ---------------------------------------------------------------------------
 
 SANDBOX_PROVIDER=modal
+# Set modal-vm for deployment-wide Docker-capable VMs; see docs/MODAL_DOCKER.md.
 
 # Modal. The API secret is shared with the Modal deployment for HMAC-signed
 # endpoint calls; the workspace and environment build the endpoint URLs.

.github/workflows/terraform.yml

@@ -122,6 +122,13 @@ jobs:
         run: terraform test
         working-directory: ${{ env.TF_WORKING_DIR }}
 
+      - name: Modal module contract tests
+        id: modal_test
+        run: |
+          terraform init -backend=false
+          terraform test
+        working-directory: terraform/modules/modal-app
+
       - name: Post Validation Results
         if: always() && github.event_name == 'pull_request'
         uses: actions/github-script@v8
@@ -140,6 +147,7 @@ jobs:
             | Init | ${{ steps.init.outcome == 'success' && '✅' || '❌' }} |
             | Validate | ${{ steps.validate.outcome == 'success' && '✅' || '❌' }} |
             | Tests | ${{ steps.test.outcome == 'success' && '✅' || '❌' }} |
+            | Modal module tests | ${{ steps.modal_test.outcome == 'success' && '✅' || '❌' }} |
             ${planNote}
 
             *Pushed by: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;

docs/GETTING_STARTED.md

@@ -160,8 +160,9 @@ Create an R2 API Token:
 
 ### Modal
 
-> Only required when `sandbox_provider = "modal"` (the default, used by the core path). To use
-> Daytona, Vercel Sandboxes, OpenComputer, or E2B instead, skip this section and follow
+> Only required when `sandbox_provider = "modal"` (the default, used by the core path) or
+> `"modal-vm"`. Select `modal-vm` for Docker-capable VMs; see [Modal VM setup](MODAL_DOCKER.md). To
+> use Daytona, Vercel Sandboxes, OpenComputer, or E2B instead, skip this section and follow
 > [Alternative Sandbox Providers](#alternative-sandbox-providers-optional).
 
 1. Go to [Modal Settings](https://modal.com/settings)

docs/MODAL_DOCKER.md

@@ -0,0 +1,76 @@
+# Modal VM backend
+
+Open Inspect offers two Modal compute backends:
+
+| `SANDBOX_PROVIDER` | Runtime                 | User Docker workloads |
+| ------------------ | ----------------------- | --------------------- |
+| `modal` (default)  | Existing gVisor sandbox | Not enabled           |
+| `modal-vm`         | Modal VM                | Included              |
+
+Selection is deployment-wide. There is no Docker checkbox or repository/session override. Mixed use
+within one deployment is a follow-up. Both backends share a Modal app, account, credentials,
+transport, and implementation; they have separate prepared-image pools.
+
+## Deployment
+
+For Terraform, set `sandbox_provider = "modal-vm"`. The existing Modal module builds and verifies
+the Docker image before deploying the worker. No extra provisioning/admission flag is required. For
+a standalone control plane, set `SANDBOX_PROVIDER=modal-vm` and provision the data plane first:
+
+```bash
+cd packages/modal-infra
+BUILD_MODAL_VM_IMAGE=true uv run python deploy.py --build-sandbox-image
+BUILD_MODAL_VM_IMAGE=true uv run modal deploy deploy.py
+```
+
+These commands create billable resources. Use the intended Modal environment and credentials. Never
+deploy `src/app.py` directly. VM launches reject old or incompatible API responses rather than
+falling back to standard sandboxes. Existing standard clients can still use the standard endpoints.
+
+## Runtime and resources
+
+The harness, bridge, workspace, IDE, and desktop run directly on the VM host. Docker is for user
+workloads such as PostgreSQL, Redis, and container builds. The runtime supervises the local daemon;
+user environment variables cannot enable Docker or redirect its readiness probes.
+
+Generic `cpuCores` and `memoryMib` size the **outer VM**, not individual containers. Missing/null
+values select the offering defaults (currently 2 cores and 4096 MiB). Positive explicit settings
+override them. VM image builds use their scope's configured resources. Standard build sizing is
+unchanged. These values are product defaults, not claimed Modal minimums.
+
+## Snapshots and recovery
+
+VM session snapshots are **destructive**: quiesce Docker, capture the filesystem, then confirm VM
+termination. Later work restores into a new VM. Standard Modal snapshots remain non-destructive. A
+failed or ambiguous capture/retirement must not be reported as a successful checkpoint.
+
+VMs therefore keep running between turns. They are saved and stopped on inactivity, lifetime expiry,
+a lost heartbeat, a runtime failure or archive; a VM that stops heartbeating is captured without its
+runtime. Cancelling a session stops its VM without saving. While a save has failed or its result is
+unknown, new prompts are held and the session offers to retry the save, restore the last saved
+state, or discard the VM and start fresh.
+
+Filesystem capture is not process/RAM continuity or an application-consistent database backup.
+Containers must use appropriate persistence and restart policies. Live Docker pause/resume is not
+provided. Raw daemon logs are truncated after clean preparation before reusable image capture.
+
+Retried VM launches adopt only an exactly owned allocation and recover its original interactive
+credentials. A predecessor must be confirmed terminated before launching a replacement. Build
+allocations have deterministic backend/build names, so a retried create adopts the allocation an
+earlier lost response created. Returned build handles are persisted for cleanup before backend
+validation; incompatible builds never start and cannot publish prepared images.
+
+## Switching backends
+
+Changing `SANDBOX_PROVIDER` is an operator cutover, not session migration. Existing sessions and
+snapshots may become unusable. Drain/retire active allocations first when feasible, retain
+credentials for pending cleanup, and rebuild images under the selected backend. Do not relabel old
+artifacts. Rollback to `modal` does not transparently resume VM sessions or prove old VMs have
+stopped.
+
+PR #2007's earlier per-session Docker/variant design was not deployed. Its schema additions and
+settings are not part of this implementation, so no variant migration is required.
+
+Provider-backed canaries must validate Docker startup, build/restore, access after adoption,
+snapshot/retirement, and cleanup in the target deployment before production rollout. Unit tests
+alone do not prove those provider behaviors.

packages/control-plane/src/image-builds/modal-adapter.test.ts

@@ -41,6 +41,10 @@ function createPlan(): ImageBuildPlan {
 }
 
 describe("ModalImageBuildAdapter", () => {
+  it("does not advertise unbound source recovery", () => {
+    expect("recoverUnboundSource" in new ModalImageBuildAdapter(createProvider())).toBe(false);
+  });
+
   it("delegates build startup to the Modal provider", async () => {
     const provider = createProvider();
     const adapter = new ModalImageBuildAdapter(provider);

packages/control-plane/src/image-builds/modal-adapter.ts

@@ -23,6 +23,7 @@ export class ModalImageBuildAdapter implements ImageBuildAdapter {
     await this.provider.triggerImageBuild({
       scopeKind: plan.scope.kind,
       scopeId: plan.scope.id,
+      resources: plan.resources,
       buildId: plan.buildId,
       repositories: plan.repositories,
       cloneToken: plan.cloneAuth.type === "credential_helper" ? plan.cloneAuth.token : undefined,

packages/control-plane/src/image-builds/model.ts

@@ -13,9 +13,10 @@ import {
   formatRepositoryFullName,
   parseRepositoryFullName,
 } from "@open-inspect/shared/types/repositories";
-import type {
-  ImageBuildScopeKind,
-  ImageBuildStatus,
+import {
+  IMAGE_BUILD_PROVIDER_IDS,
+  type ImageBuildScopeKind,
+  type ImageBuildStatus,
 } from "@open-inspect/shared/types/image-builds";
 import type { HarnessId } from "@open-inspect/shared/harnesses";
 import { z } from "zod";
@@ -24,21 +25,7 @@ import {
   MIN_COMPATIBLE_RUNTIME_GENERATION,
 } from "../sandbox/runtime-manifest";
 
-/**
- * Providers with image-build support: Modal images, Vercel snapshots,
- * OpenComputer checkpoints, E2B snapshots, Daytona snapshots.
- *
- * Support is the provider's ability to build and boot an artifact. Whether a
- * deployment may start new Daytona builds is a separate, operator-owned
- * question — see `resolveImageBuildAdmission` in provider-policy.ts.
- */
-export const IMAGE_BUILD_PROVIDER_IDS = [
-  "modal",
-  "vercel",
-  "opencomputer",
-  "e2b",
-  "daytona",
-] as const;
+export { IMAGE_BUILD_PROVIDER_IDS } from "@open-inspect/shared/types/image-builds";
 
 export const imageBuildProviderSchema = z.enum(IMAGE_BUILD_PROVIDER_IDS);
 

packages/control-plane/src/image-builds/planner.ts

@@ -99,6 +99,7 @@ export class ImageBuildPlanner implements ImageBuildPlannerPort {
       callbackUrl: params.callbackUrl,
       failureCallbackUrl: params.failureCallbackUrl,
       buildTimeoutMs: resolveBuildTimeoutSeconds(sandboxSettings) * MS_PER_SECOND,
+      resources: { cpuCores: sandboxSettings.cpuCores, memoryMib: sandboxSettings.memoryMib },
       userEnvVars: userEnvVars
         ? prepareLegacyManagedProviderEnv({
             exposedSecrets: userEnvVars,

packages/control-plane/src/image-builds/provider-factory.ts

@@ -37,7 +37,8 @@ class EnvImageBuildAdapterFactory implements ImageBuildAdapterFactory {
   create(provider: ImageBuildProvider, operation: "start" | "existing_session"): ImageBuildAdapter {
     switch (provider) {
       case "modal":
-        return new ModalImageBuildAdapter(createSandboxProviderFromEnv(this.env, "modal"));
+      case "modal-vm":
+        return new ModalImageBuildAdapter(createSandboxProviderFromEnv(this.env, provider));
       case "vercel":
         return new VercelImageBuildAdapter(createSandboxProviderFromEnv(this.env, "vercel"));
       case "opencomputer":

packages/control-plane/src/image-builds/types.ts

@@ -1,4 +1,5 @@
 import type { RepositoryShaEntry } from "@open-inspect/shared/types/image-builds";
+import type { SandboxSettings } from "@open-inspect/shared/types/integrations";
 import type { CorrelationContext } from "../logger";
 import type { ImageBuildProviderImageRef, ImageBuildScope } from "./model";
 
@@ -32,6 +33,7 @@ export type ImageBuildCloneAuth =
  * Every supported provider uses the same create-bind-launch session contract.
  */
 export interface ImageBuildPlan {
+  resources?: Pick<SandboxSettings, "cpuCores" | "memoryMib">;
   buildId: string;
   scope: ImageBuildScope;
   repositories: ImageBuildRepository[];

packages/control-plane/src/routes/image-builds.trigger.test.ts

@@ -205,6 +205,7 @@ const registerBuildSpy = vi.spyOn(ImageBuildStore.prototype, "registerBuild");
 const getActiveBuildSpy = vi.spyOn(ImageBuildStore.prototype, "getActiveBuild");
 const hasReadyImageSpy = vi.spyOn(ImageBuildStore.prototype, "hasReadyImageForFingerprint");
 const markBuildFailedSpy = vi.spyOn(ImageBuildStore.prototype, "markBuildFailed");
+const markSourceCreateIntentSpy = vi.spyOn(ImageBuildStore.prototype, "markSourceCreateIntent");
 const bindProviderSessionSpy = vi.spyOn(ImageBuildStore.prototype, "bindProviderSession");
 const setImageBuildEnabledSpy = vi.spyOn(RepoMetadataStore.prototype, "setImageBuildEnabled");
 
@@ -220,6 +221,7 @@ beforeEach(() => {
   markBuildFailedSpy.mockResolvedValue(true);
   setImageBuildEnabledSpy.mockResolvedValue(undefined);
   bindProviderSessionSpy.mockResolvedValue(true);
+  markSourceCreateIntentSpy.mockResolvedValue(true);
   modalClient.createImageBuildSandbox.mockResolvedValue({
     providerSessionId: "modal-session-1",
   });