humanish 0.137.0 → 0.139.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.139.0: Computer-use studies can run on Modal desktops (2026-10-19)
+
+humanish 0.139.0 can run a computer-use study's desktops on Modal. Set
+`execution.target: modal-desktop` on an `app-url` study and each participant gets its own Modal
+sandbox running the same desktop the E2B route uses: Xvfb, XFCE, xdotool input, screenshots, a
+live noVNC stream, Chromium and recordings. The same study file runs on E2B or Modal
+with only the target changed. Clone and local-tree subjects, shared worlds, E2B templates and
+camera or speech media stay on E2B.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.139.0)
+
+## 0.138.0: A terminal study can run on Modal (2026-10-19)
+
+humanish 0.138.0 can run a terminal study's shell on Modal as well as E2B. Set
+`execution.target: modal-terminal` and `execution.runtimeAuth: openai-env`, sign in with
+`modal token new`, and install the optional `modal` package beside humanish. The sandbox runs as a
+non-root user with sudo, as on E2B, lives up to Modal's 24 hours, is journaled and reclaimed by id
+like an E2B sandbox, and is priced at Modal's sandbox rate. Desktop studies still run on E2B or a
+local VM.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.138.0)
+
 ## 0.137.0: Each browser participant can record its requests (2026-10-16)
 
 humanish 0.137.0 can record the requests each hosted browser participant makes. With

package/dist/cli/commands/runs.js

@@ -203,12 +203,12 @@ export function registerRuntimeCommands(parent, io) {
 export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
-        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox E2B lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks E2B whether each still exists and kills nothing. Needs E2B_API_KEY in the environment or in --dotenv.")
+        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox the run's provider lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks the provider whether each still exists and kills nothing. Needs E2B_API_KEY, or MODAL_TOKEN_ID and MODAL_TOKEN_SECRET for a run on Modal, in the environment or in --dotenv.")
         .summary("Stop or check an interrupted run's sandboxes.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
-        .option("--check", "Ask E2B whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
+        .option("--check", "Ask the provider whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
         .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
         .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)

package/dist/cli/doctor.js

@@ -96,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
     const checks = [
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
+        ...(setup?.keys.includes("MODAL_TOKEN_ID") === true ? [await modalSdkCheck()] : []),
         sandboxCeilingCheck(env),
         concurrentSandboxesCheck(env),
         terminalSurfaceCheck(),
@@ -239,6 +240,25 @@ async function desktopSdkCheck(setup) {
                 : missingDesktopSdkMessage(humanishInstall()),
     };
 }
+/** The optional `modal` peer, reported only for a study that runs on Modal, which needs it. */
+async function modalSdkCheck() {
+    const present = await safeCheck(async () => {
+        try {
+            await import("modal");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return {
+        name: "modal sdk",
+        ok: present,
+        message: present
+            ? "optional peer modal is installed; provider access is not tested"
+            : `optional peer modal is absent, and this study runs on Modal. ${desktopPeerAdvice(humanishInstall(), "modal").advice}`,
+    };
+}
 /**
  * The stakeholder surface. Reported as capability, never as a gate: the TUI is optional,
  * and `doctor` is itself mostly run by agents through a pipe, where a TTY requirement says
@@ -288,6 +308,10 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     if (study) {
         const { resolveStudyManifest } = await import("../study/discover.js");
         const resolved = await resolveStudyManifest(cwd, study);
+        // A study on Modal reads the Modal token pair, which no other study needs.
+        if (resolved.ok && resolved.config.execution?.target === "modal-terminal")
+            for (const name of ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"])
+                keyNames.add(name);
         if (resolved.ok && resolved.config.comms?.email?.kind === "real") {
             const { receivingRequiredKey } = await import("../comms/setup.js");
             receivingKey = await receivingRequiredKey(cwd, resolved.config.comms.email.connection);

package/dist/keys/key-resolution.js

@@ -7,6 +7,7 @@
 //      examples document;
 //   3. the owning vendor's native store, where one exists:
 //        E2B_API_KEY  <- ~/.e2b/config.json (written by `e2b auth login`);
+//        MODAL_TOKEN_ID, MODAL_TOKEN_SECRET <- ~/.modal.toml (written by `modal token new`);
 //        GH_TOKEN     <- `gh auth token` (the gh CLI's credential chain);
 //   4. the humanish user-level store `$XDG_CONFIG_HOME/humanish/keys.env`, written only by
 //      `humanish keys set` (0600, prompted or --stdin), the fallback for vendors that ship
@@ -20,6 +21,7 @@ import { spawn } from "node:child_process";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync, } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { parse as parseToml } from "smol-toml";
 import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
 import { humanishConfigFile } from "../cli/user-config.js";
@@ -48,6 +50,14 @@ const PROVIDER_KEYS = [
         listed: { order: 1, use: "hosted desktops" },
         doctor: true,
     },
+    {
+        name: "MODAL_TOKEN_ID",
+        vendor: "modal",
+        login: "modal token new",
+    },
+    { name: "MODAL_TOKEN_SECRET", login: "modal token new" },
+    // Which Modal environment sandboxes are created in; not a secret, but it names the account.
+    { name: "MODAL_ENVIRONMENT" },
     { name: "ANTHROPIC_API_KEY", vendor: "anthropic" },
     {
         name: "GH_TOKEN",
@@ -81,6 +91,36 @@ export function userKeyStorePath(env, deps = {}) {
 function e2bConfigPath(deps) {
     return path.join(deps.homeDir ?? homedir(), ".e2b", "config.json");
 }
+/**
+ * The token pair and environment of the Modal CLI's profile, as Modal picks it: MODAL_PROFILE
+ * when set, else the profile marked `active`, else the only profile. Null when there is none.
+ */
+function readModalProfile(env, deps) {
+    try {
+        const file = env.MODAL_CONFIG_PATH?.trim() || path.join(deps.homeDir ?? homedir(), ".modal.toml");
+        if (!isRegularFile(file))
+            return null;
+        const profiles = [];
+        for (const [name, values] of Object.entries(parseToml(readFileSync(file, "utf8"))))
+            if (values !== null && typeof values === "object" && !Array.isArray(values))
+                profiles.push([name, values]);
+        const named = env.MODAL_PROFILE?.trim();
+        const profile = named
+            ? profiles.find(([name]) => name === named)?.[1]
+            : (profiles.find(([, values]) => values.active === true)?.[1] ??
+                (profiles.length === 1 ? profiles[0]?.[1] : undefined));
+        const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+        const tokenId = text(profile?.token_id);
+        const tokenSecret = text(profile?.token_secret);
+        if (tokenId === undefined || tokenSecret === undefined)
+            return null;
+        const environment = text(profile?.environment);
+        return { tokenId, tokenSecret, ...(environment === undefined ? {} : { environment }) };
+    }
+    catch {
+        return null;
+    }
+}
 /** Default exec: bounded, quiet, stdin closed; null on any failure. Never throws. */
 function defaultExecText(command, args, timeoutMs, env) {
     return new Promise((resolve) => {
@@ -205,7 +245,18 @@ export async function discoverProviderKeys(args) {
         if (teamKey !== null)
             fill("E2B_API_KEY", teamKey, "~/.e2b/config.json (e2b auth login)");
     }
-    // Rung 3b: the gh CLI's credential chain. Only consulted when neither GitHub env name is
+    // Rung 3b: the modal CLI's profile. Both tokens come from the same profile or neither does.
+    if (fillable("MODAL_TOKEN_ID") && fillable("MODAL_TOKEN_SECRET")) {
+        const profile = readModalProfile(env, deps);
+        if (profile !== null) {
+            const source = "~/.modal.toml (modal token new)";
+            fill("MODAL_TOKEN_ID", profile.tokenId, source);
+            fill("MODAL_TOKEN_SECRET", profile.tokenSecret, source);
+            if (profile.environment !== undefined && fillable("MODAL_ENVIRONMENT"))
+                fill("MODAL_ENVIRONMENT", profile.environment, source);
+        }
+    }
+    // Rung 3c: the gh CLI's credential chain. Only consulted when neither GitHub env name is
     // present; fills GH_TOKEN (the name humanish reads first). gh runs without any provider key in
     // its environment, so the keys the rungs above just filled stay in this process.
     if (fillable("GH_TOKEN") && fillable("GITHUB_TOKEN")) {
@@ -265,7 +316,7 @@ export function describeMissingKeys(names, env) {
     const strict = env.HUMANISH_STRICT_KEYS?.trim() === "1";
     const chain = strict
         ? "key discovery is disabled (HUMANISH_STRICT_KEYS=1); only process env and --dotenv are read"
-        : `also checked ${PROJECT_OVERLAY_RELATIVE}, ~/.e2b/config.json, gh auth token, and ${path.join("~", ".config", "humanish", "keys.env")}`;
+        : `also checked ${PROJECT_OVERLAY_RELATIVE}, ~/.e2b/config.json, ~/.modal.toml, gh auth token, and ${path.join("~", ".config", "humanish", "keys.env")}`;
     return `${chain}. Fill: ${hints}.`;
 }
 /**

package/dist/routes/computer-use/bundle-parts.d.ts

@@ -15,7 +15,10 @@ export declare function describeSubjectState(state: RunSubjectProvenance["state"
 /** Human-readable provenance line for the single-participant subject.provenance event of a clone
  *  or local-tree subject: claims "cloned/packed and served" only when it actually happened. */
 export declare function subjectProvenanceMessage(provenance: RunSubjectProvenance, publicAppUrl: string, dryRun: boolean, hasSession: boolean): string;
+/** The label a run records for the desktop `execution.target` names. */
+export declare function desktopSubstrate(target: string | undefined): "local-desktop" | "modal-desktop" | "e2b-desktop";
 export declare function providerResourcesForOutcome(args: {
+    provider: "e2b-desktop" | "modal-desktop";
     outcome: ParticipantRunOutcome | undefined;
     createdAt: string;
     ids: ParticipantIds;

package/dist/routes/computer-use/bundle-parts.js

@@ -73,6 +73,14 @@ export function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSe
     }
     return "Subject local-tree packing attempted; archive digest unresolved (provisioning failed before resolution)";
 }
+/** The label a run records for the desktop `execution.target` names. */
+export function desktopSubstrate(target) {
+    return target === "local"
+        ? "local-desktop"
+        : target === "modal-desktop"
+            ? "modal-desktop"
+            : "e2b-desktop";
+}
 export function providerResourcesForOutcome(args) {
     if (args.outcome?.sandboxId === undefined) {
         return [];
@@ -80,7 +88,7 @@ export function providerResourcesForOutcome(args) {
     return [
         {
             schema: "humanish.provider-resource.v1",
-            provider: "e2b-desktop",
+            provider: args.provider,
             kind: "sandbox",
             id: args.outcome.sandboxId,
             owner: "humanish",

package/dist/routes/computer-use/bundle.js

@@ -6,7 +6,7 @@ import { judgeOneParticipant, judgeParticipants } from "../../run/judge.js";
 import { renderReviewMarkdown } from "../../run/review-markdown.js";
 import { desktopSpanToMinutes } from "../../run/cost-summary.js";
 import { e2bDesktopTemplate } from "../../substrates/e2b/sandbox.js";
-import { providerResourcesForOutcome } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome } from "./bundle-parts.js";
 import { participantFactsOf } from "./participant-facts.js";
 import { buildCuaFanoutBundle } from "./fanout-bundle.js";
 import { buildSingleParticipantBundle } from "./single-bundle.js";
@@ -96,9 +96,7 @@ function singleParticipantArgs(base, state) {
         desktopRoute: base.plan.runner.desktop !== "in-process",
         substrate: base.plan.runner.desktop === "in-process"
             ? "local-filesystem"
-            : plan.residual.execution?.target === "local"
-                ? "local-desktop"
-                : "e2b-desktop",
+            : desktopSubstrate(plan.residual.execution?.target),
         ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
         ...(outcome?.networkLog === undefined ? {} : { network: outcome.networkLog }),
@@ -127,6 +125,7 @@ function singleParticipantArgs(base, state) {
         ...(desktopTemplate === undefined ? {} : { desktopTemplate }),
         ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),
         providerResources: providerResourcesForOutcome({
+            provider: base.plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
             outcome,
             createdAt: base.run.createdAt,
             ids: spec,

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -11,6 +11,7 @@ import { observeDesktopResources } from "../../../substrates/e2b/desktop-resourc
 import { acquireE2BDesktopSandbox, e2bDesktopTemplate, withOneRetryOnTransientE2BError, } from "../../../substrates/e2b/sandbox.js";
 import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
+import { loadModalDesktopModule } from "../../../substrates/modal/sandbox.js";
 import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
 import { participantSubjectEnv } from "../types.js";
 import { plural } from "../../../run/text.js";
@@ -30,11 +31,14 @@ export async function acquireParticipantDesktop(ctx, state) {
     // Off-app comms: the base-URL env is injected at sandbox create, so the app reads it at
     // boot; the catch starts right after create.
     const commsEnv = participantCommsEnv(ctx.comms);
-    const desktopModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
+    const provider = deps.sandboxProvider ?? "e2b";
+    const desktopModule = await (deps.desktopModule ??
+        (provider === "modal" ? () => loadModalDesktopModule(env) : loadE2BDesktopModule))();
     // An explicit template wins. Speech gets the versioned media image; ordinary
-    // browser studies retain the SDK default desktop.
+    // browser studies retain the SDK default desktop. A Modal desktop has one image.
     const acquired = await acquireE2BDesktopSandbox({
         module: desktopModule,
+        provider,
         options: {
             apiKey: deps.e2bApiKey,
             requestTimeoutMs: deps.requestTimeoutMs,
@@ -67,7 +71,7 @@ export async function acquireParticipantDesktop(ctx, state) {
             dpi: 96,
             lifecycle: { onTimeout: "kill" },
         },
-        template: e2bDesktopTemplate(residual),
+        template: provider === "modal" ? undefined : e2bDesktopTemplate(residual),
         retry: {
             // The default loader reclaims an acquired handle before retrying failed desktop startup.
             // Its error names the cleanup outcome; pre-construction allocation failures remain unowned.
@@ -92,7 +96,7 @@ export async function acquireParticipantDesktop(ctx, state) {
     state.sandboxId = acquired.allocation.resourceId;
     // The billed span starts the instant the sandbox exists.
     state.sandboxCreatedAtMs = deps.now();
-    const desktopResources = await observeDesktopResources(desktop);
+    const desktopResources = await observeDesktopResources(desktop, undefined, provider === "modal" ? "modal.create" : "e2b.getInfo");
     state.desktopResources = desktopResources;
     if ("reason" in desktopResources) {
         warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);

package/dist/routes/computer-use/fanout-bundle.js

@@ -5,7 +5,7 @@ import { cuaGoalSource } from "../../actors/goal-source.js";
 import { redactEncodedText } from "../../evidence/encoded-text.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, gapsListClause, skippedSentence, withCuaReviewProvenance, } from "../../run/outcomes.js";
-import { providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps, } from "./bundle-parts.js";
 import { subjectName } from "../../run/subject-name.js";
 import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { participantFactsOf } from "./participant-facts.js";
@@ -179,7 +179,7 @@ function fanoutFeedbackCandidates(args) {
             runId: args.run.runId,
             scenarioId: `cua-${plan.studyId}`,
             adapterId: plan.studyId,
-            substrate: plan.residual.execution?.target === "local" ? "local-desktop" : "e2b-desktop",
+            substrate: desktopSubstrate(plan.residual.execution?.target),
             participants: specs.map((spec, index) => {
                 const outcome = outcomes?.[index];
                 return {
@@ -241,6 +241,7 @@ export function buildCuaFanoutBundle(args) {
     const desktopTemplate = e2bDesktopTemplate(plan.residual);
     const desktopBrowser = fanoutDesktopBrowser(args);
     const providerResources = (outcomes ?? []).flatMap((outcome) => providerResourcesForOutcome({
+        provider: plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
         outcome,
         createdAt: args.run.createdAt,
         ids: outcome.spec,

package/dist/routes/computer-use/participant-deps.d.ts

@@ -36,7 +36,7 @@ interface DesktopRunFacts {
 }
 /** The fields one desktop route sets and the other does not. Undefined leaves a field out. */
 type DesktopRouteOverrides = {
-    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "desktopFiles" | "externalComms" | "receiving" | "screenMismatchPolicy"]?: CuaParticipantDeps[K] | undefined;
+    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "desktopFiles" | "externalComms" | "receiving" | "screenMismatchPolicy" | "sandboxProvider"]?: CuaParticipantDeps[K] | undefined;
 };
 /**
  * One run's participant deps. Call it once per run: the run budget it creates is the one ledger

package/dist/routes/computer-use/plan.js

@@ -2,6 +2,7 @@
 // in its order and with its codes, then the plan the run uses. What stays in the route reads
 // external state: committed personas, a rerun's source run, keys, the local agent, subject env
 // values, spend-cap prices and the comms catch.
+import { MODAL_MAX_SANDBOX_MS } from "../../substrates/modal/sdk.js";
 import { DESKTOP_FILES_ROUTE_REASON } from "../../study/desktop-files.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
@@ -206,12 +207,14 @@ function startsOf(config, runner, limits, ceilingMs) {
     const declared = config.execution?.concurrency;
     const n = runner.participants.length;
     const hosted = runner.desktop === "e2b-desktop";
+    // The E2B plan's limit binds only E2B desktops; Modal's container limit is far above a study's.
+    const e2bHosted = hosted && runner.provider === "e2b";
     const atOnce = participantsAtOnce({
         concurrency: boundedConcurrency(declared, n),
         declared: declared !== undefined,
         participants: n,
     }, {
-        ...(hosted ? { sandboxes: limits.concurrentSandboxes } : {}),
+        ...(e2bHosted ? { sandboxes: limits.concurrentSandboxes } : {}),
         cap: limits.concurrencyCap,
     });
     if (!atOnce.ok)
@@ -265,6 +268,54 @@ function timeZoneRunnerReason(desktop, participants) {
         ? `${declared} This study runs on the local browser runtime. Remove actor.clock and participants[].clock, or set execution.target: e2b-desktop.`
         : `${declared} This study drives your own browser through RunStudyOptions.inProcess. Remove actor.clock and participants[].clock, and set the zone in that browser yourself, or run on a hosted desktop.`;
 }
+/** Who hosts the study's desktops and the longest sandbox they allow, or why it cannot run. */
+function hostingOf(config, e2bCeiling) {
+    if (config.execution?.target !== "modal-desktop")
+        return e2bCeiling.ok
+            ? { provider: "e2b", ceiling: e2bCeiling }
+            : { refusal: e2bCeiling.message };
+    const refusal = modalDesktopRefusal(config);
+    return refusal === undefined
+        ? { provider: "modal", ceiling: { ms: MODAL_MAX_SANDBOX_MS } }
+        : { refusal };
+}
+/** The app-url subject the study names, and the subject a hosted desktop provisions. */
+function subjectsOf(config) {
+    const appUrl = config.subject.appUrl ?? "";
+    const declaredServeUrl = config.subject.serve?.url;
+    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
+    const appUrlSubject = {
+        kind: "app-url",
+        appUrl,
+        publicTargets: config.policies?.allowPublicTargets === true,
+        ...serveUrl,
+    };
+    const product = config.subject.product;
+    const hosted = config.subject.source === "desktop-cli" && product !== undefined
+        ? { kind: "desktop-cli", product, ...serveUrl }
+        : (provisionedSubject(config) ?? appUrlSubject);
+    return { appUrl, appUrlSubject, hosted };
+}
+/**
+ * What a study on a Modal desktop cannot have that one on an E2B desktop can, or undefined. The
+ * Modal desktop runs an app-url subject in Chromium; provisioned subjects, a terminal subject,
+ * E2B templates and the speech template are E2B's.
+ */
+function modalDesktopRefusal(config) {
+    const desktop = config.execution?.desktop;
+    if (config.subject.source !== "app-url")
+        return `A Modal desktop runs app-url subjects only, and this study's subject is ${config.subject.source}. Set execution.target: e2b-desktop.`;
+    if (config.route === "shared-world")
+        return "A shared-world study runs on E2B desktops only. Set execution.target: e2b-desktop.";
+    if (desktop?.template !== undefined)
+        return "execution.desktop.template names an E2B template, which a Modal desktop cannot use. Remove it, or set execution.target: e2b-desktop.";
+    if (desktop?.media !== undefined)
+        return "execution.desktop.media needs the E2B speech or camera template, which a Modal desktop does not have. Remove it, or set execution.target: e2b-desktop.";
+    const browser = desktop?.browser;
+    if (browser !== undefined && browser !== "default" && browser !== "chromium")
+        return `A Modal desktop has Chromium only, and execution.desktop.browser is ${browser}. Set it to chromium or default, or set execution.target: e2b-desktop.`;
+    return undefined;
+}
 /** What the participants declare that this runner cannot do, with its code, or undefined. */
 function runnerRefusal(desktop, participants) {
     const files = desktopFilesRunnerReason(desktop, participants);
@@ -304,9 +355,10 @@ export function planComputerUseStudy(config, input) {
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("in-scope", "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
-    const ceiling = input.sandboxCeiling;
-    if (!ceiling.ok)
-        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", ceiling.message, actor);
+    const hosting = hostingOf(config, input.sandboxCeiling);
+    if ("refusal" in hosting)
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", hosting.refusal, actor);
+    const { provider, ceiling } = hosting;
     const rejection = cuaStudyRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving), ceiling.ms);
     if (rejection)
         return refuse("in-scope", rejection.code, rejection.message, actor);
@@ -335,19 +387,7 @@ export function planComputerUseStudy(config, input) {
         return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunStudyOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
     if (first === undefined)
         throw new Error("computerUseParticipants returned no participant");
-    const appUrl = config.subject.appUrl ?? "";
-    const declaredServeUrl = config.subject.serve?.url;
-    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
-    const appUrlSubject = {
-        kind: "app-url",
-        appUrl,
-        publicTargets: config.policies?.allowPublicTargets === true,
-        ...serveUrl,
-    };
-    const product = config.subject.product;
-    const hosted = source === "desktop-cli" && product !== undefined
-        ? { kind: "desktop-cli", product, ...serveUrl }
-        : (provisionedSubject(config) ?? appUrlSubject);
+    const { appUrl, appUrlSubject, hosted } = subjectsOf(config);
     const brain = brainOf(config, driving.createProvider);
     const runner = driving.inProcess
         ? {
@@ -358,7 +398,13 @@ export function planComputerUseStudy(config, input) {
         }
         : isLocalBrowserStudy(config)
             ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
-            : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
+            : {
+                desktop: "e2b-desktop",
+                provider,
+                brain,
+                participants: [first, ...rest],
+                subject: hosted,
+            };
     const unsupported = runnerRefusal(runner.desktop, participants);
     if (unsupported)
         return refuse("in-scope", unsupported.code, unsupported.message, actor);
@@ -382,7 +428,8 @@ export function planComputerUseStudy(config, input) {
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []
                 : desktopRequirements(config, {
-                    e2b: runner.desktop === "e2b-desktop",
+                    e2b: runner.desktop === "e2b-desktop" && runner.provider === "e2b",
+                    modal: runner.desktop === "e2b-desktop" && runner.provider === "modal",
                     brain,
                     localVm: runner.desktop === "local-vm",
                     externalCatch: !provisioned,

package/dist/routes/computer-use/setup.js

@@ -125,13 +125,8 @@ export async function admitCuaRun(plan, input, config) {
     // Read keys once into locals (names only; values never logged or persisted).
     const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
-    // Literal scrubber for every known provisioned value (no secret "shape" to pattern-match).
-    // Dry and in-process runs scrub both keys too: a mission or persona can still quote them.
-    const secrets = new RunSecrets([
-        openaiApiKey,
-        e2bApiKey,
-        ...subjectEnvNames.map((name) => env[name] ?? ""),
-    ]);
+    // Every known key and subject value, scrubbed literally, in dry and in-process runs too.
+    const secrets = new RunSecrets([openaiApiKey, e2bApiKey, ...otherValues(env, subjectEnvNames)]);
     sanitizeParticipantRuns(participantRuns, secrets.scrub);
     const desktopFiles = await readStudyDesktopFiles(input.cwd, plan, participantRuns, secrets.scrub);
     if (!desktopFiles.ok)
@@ -342,6 +337,7 @@ function cuaParticipantDeps(plan, input, admitted, run) {
         prepareDesktop: input.prepareDesktop,
     }, {
         createDesktop: input.localVm?.desktop,
+        sandboxProvider: plan.runner.desktop === "e2b-desktop" ? plan.runner.provider : undefined,
         ...callerDriving(input, config),
         localTreeArchiveBuffer: admitted.localTreeArchiveBuffer,
         desktopFiles: admitted.desktopFiles.size === 0 ? undefined : admitted.desktopFiles,
@@ -373,3 +369,14 @@ function subjectPhaseReporter(input) {
         input.emit?.(phaseEvent(event, { kind: "participant", participant }));
     };
 }
+/**
+ * The Modal token pair's values, which a provider error can quote into run warnings, and the
+ * subject env values the study names.
+ */
+function otherValues(env, subjectEnv) {
+    return [
+        env.MODAL_TOKEN_ID?.trim() ?? "",
+        env.MODAL_TOKEN_SECRET?.trim() ?? "",
+        ...subjectEnv.map((name) => env[name] ?? ""),
+    ];
+}

package/dist/routes/computer-use/types.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxProviderId } from "../../run/sandbox-receipts.js";
 import type { Verdict } from "../../run/judge.js";
 import type { HostSuspensionReading } from "../../run/host-suspension.js";
 import type { LocalCapacity } from "../../substrates/local/capacity.js";
@@ -344,6 +345,8 @@ export interface E2BDesktopDeps {
     now: () => number;
     /** Loads the E2B SDK for the participant's desktop. Defaults to loadE2BDesktopModule. */
     desktopModule?: () => Promise<E2BDesktopModule>;
+    /** Who hosts the participant's desktop; E2B when unset. */
+    sandboxProvider?: SandboxProviderId;
     /** The caller's prepareDesktop, called with the participant as its target. */
     prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     /** Clock and sleep for detached provisioning steps. */

package/dist/routes/terminal/live-sandbox.d.ts

@@ -26,6 +26,8 @@ export interface LiveSandboxInputs {
     verdictNonce: string;
     maxMinutes: number;
     e2bApiKey: string;
+    /** The run's env; a Modal run reads its Modal credentials from it. */
+    env: Readonly<Record<string, string | undefined>>;
     runPaths: StartedRun["paths"];
     metadata: ReturnType<typeof buildSandboxMetadata>;
     /** The run's warnings. Steps append to them. */

package/dist/routes/terminal/live-sandbox.js

@@ -11,6 +11,7 @@ import { extractLocalActorVerdict, normalizeLocalActorTranscript, } from "../../
 import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { observeDesktopResources, } from "../../substrates/e2b/desktop-resources.js";
 import { acquireE2BShellSandbox } from "../../substrates/e2b/sandbox.js";
+import { loadModalShellModule } from "../../substrates/modal/sandbox.js";
 import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
@@ -60,7 +61,10 @@ export class LiveTerminalSandbox {
         const { requestTimeoutMs, sandboxTimeoutMs } = this;
         // Declared egress allowlist, or undefined for the historical unrestricted default.
         const egressAllow = plan.egressAllow;
-        const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
+        const provider = plan.sandboxProvider;
+        const providerName = provider === "modal" ? "Modal" : "E2B";
+        const sandboxModule = await (deps.desktopModule ??
+            (provider === "modal" ? () => loadModalShellModule(this.inputs.env) : loadE2BDesktopModule))();
         await validatePreparedRunArtifactPaths(runPaths);
         // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
         // carries the real runtime key; participant commands receive an inert placeholder. The proxy
@@ -83,6 +87,7 @@ export class LiveTerminalSandbox {
         this.account = e2bAccount(sandboxModule, options);
         const acquired = await acquireE2BShellSandbox({
             module: sandboxModule,
+            provider,
             options,
             retry: {
                 // A failed first attempt may have allocated a sandbox whose id never reached this run;
@@ -103,8 +108,8 @@ export class LiveTerminalSandbox {
         this.sandboxId = sandboxId;
         this.createdAtMs = now();
         await validatePreparedRunArtifactPaths(runPaths);
-        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with allowlisted metadata and kill-on-timeout, and with no sandbox-wide environment variables.`);
-        const sandboxResources = await observeDesktopResources(sandbox);
+        recordLifecycle("terminal-lab.sandbox.created", `${providerName} shell sandbox ${sandboxId} created with allowlisted metadata and kill-on-timeout, and with no sandbox-wide environment variables.`);
+        const sandboxResources = await observeDesktopResources(sandbox, undefined, provider === "modal" ? "modal.create" : "e2b.getInfo");
         this.resources = sandboxResources;
         if ("reason" in sandboxResources) {
             warnings.push(`Sandbox resource size unavailable (${sandboxResources.reason}); its compute cost remains unpriced.`);