@blaxel/core 0.3.31 → 0.3.32-preview.332

package/dist/cjs/common/settings.js

@@ -30,8 +30,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.31";
-const BUILD_COMMIT = "e08b96df13cebc750a05401ee4d824d42f37a191";
+const BUILD_VERSION = "0.3.32-preview.332";
+const BUILD_COMMIT = "eeb11112e6f23be5c60b770389ef29eda8452fb0";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-09-22";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/cjs/sandbox/drift.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDrift = describeDrift;
+exports.driftWarning = driftWarning;
+// The control plane masks every env value it reads back, so values can only be compared when it did not.
+const MASKED_ENV_VALUE = "****";
+// The control plane keeps the image reference as submitted: "app" and "app:latest" are the same image.
+function withTag(image) {
+    if (image.includes("@"))
+        return image;
+    return image.indexOf(":", image.lastIndexOf("/") + 1) === -1 ? `${image}:latest` : image;
+}
+function envDrift(requested, existing) {
+    const byName = new Map(existing.map((env) => [env.name, env]));
+    const missing = [];
+    const changed = [];
+    for (const env of requested) {
+        const current = byName.get(env.name);
+        if (!current)
+            missing.push(env.name ?? "");
+        else if (current.value !== undefined && current.value !== MASKED_ENV_VALUE && current.value !== env.value)
+            changed.push(env.name ?? "");
+    }
+    // Names only: env values are often secrets and never go into a log line.
+    const parts = [
+        missing.length ? `not set on the existing sandbox: ${missing.join(", ")}` : "",
+        changed.length ? `different value: ${changed.join(", ")}` : "",
+    ].filter(Boolean);
+    return parts.length ? `envs (${parts.join("; ")})` : undefined;
+}
+/**
+ * Describes how an existing sandbox differs from the configuration that was
+ * asked for, one entry per field (image, memory, region, envs). Empty when
+ * nothing differs. A field the existing sandbox does not report is not drift.
+ */
+function describeDrift(requested, existing) {
+    const drift = [];
+    const runtime = existing.spec?.runtime;
+    if (requested.image && runtime?.image && withTag(requested.image) !== withTag(runtime.image)) {
+        drift.push(`image (requested ${requested.image}, existing ${runtime.image})`);
+    }
+    if (requested.memory !== undefined && runtime?.memory !== undefined && requested.memory !== runtime.memory) {
+        drift.push(`memory (requested ${requested.memory} MB, existing ${runtime.memory} MB)`);
+    }
+    if (requested.region && existing.spec?.region && requested.region !== existing.spec.region) {
+        drift.push(`region (requested ${requested.region}, existing ${existing.spec.region})`);
+    }
+    if (requested.envs?.length && runtime?.envs) {
+        const envs = envDrift(requested.envs, runtime.envs);
+        if (envs)
+            drift.push(envs);
+    }
+    return drift;
+}
+/** The single warning createIfNotExists logs when the sandbox it returned is not the one that was asked for. */
+function driftWarning(name, drift) {
+    return (`SandboxInstance.createIfNotExists: sandbox ${name ? `"${name}" ` : ""}already exists, so it was returned as is and the requested configuration was not applied. ` +
+        `It differs on: ${drift.join("; ")}. ` +
+        "Delete the sandbox and create it again to apply the new configuration.");
+}

package/dist/cjs/sandbox/mount-drives.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxDriveSetup = exports.SandboxDriveSetupError = exports.MOUNT_DRIVES_CONCURRENCY = void 0;
+exports.validateMountDrives = validateMountDrives;
+const uuid_1 = require("uuid");
+const index_js_1 = require("../drive/index.js");
+/** Most drive lookups/creations, mounts and deletions in flight at once. */
+exports.MOUNT_DRIVES_CONCURRENCY = 5;
+/**
+ * Thrown when `mountDrives` could not be set up. Drives this call created
+ * under a name it generated and did not mount are deleted first; a drive
+ * created under a name you chose is never deleted, since a concurrent call may
+ * be using it. `createdDrives` names the drives this call created (or may have
+ * created, when a response was lost) that are left in place.
+ *
+ * - `sandbox` is set when the sandbox is ready: it and the mounts made so far
+ *   are kept. `driveNames` lists the drives this call looked up or created that
+ *   are left in place.
+ * - `sandbox` is undefined when the sandbox could not be created (its error is
+ *   the `cause`) and some drives created for it could not be deleted. When they
+ *   all could, the sandbox's error is thrown as is instead.
+ */
+class SandboxDriveSetupError extends Error {
+    sandbox;
+    driveNames;
+    createdDrives;
+    constructor(sandbox, driveNames, createdDrives, cause) {
+        const detail = cause instanceof Error ? cause.message : JSON.stringify(cause);
+        const left = createdDrives.length ? `. Drives this call created (or may have created) are left in place: ${createdDrives.join(", ")}.` : "";
+        super(sandbox
+            ? `Sandbox ${sandbox.metadata.name} is ready, but mounting its drives failed: ${detail}${left}`
+            : `Sandbox creation failed: ${detail}${left}`, { cause });
+        this.sandbox = sandbox;
+        this.driveNames = driveNames;
+        this.createdDrives = createdDrives;
+        this.name = "SandboxDriveSetupError";
+    }
+}
+exports.SandboxDriveSetupError = SandboxDriveSetupError;
+const cleanPath = (path = "/") => `/${path.split("/").filter(Boolean).join("/")}`;
+/** The HTTP status of an API error, if it has one. */
+function httpStatus(e) {
+    if (typeof e !== "object" || e === null)
+        return undefined;
+    const error = e;
+    for (const value of [error.response?.status, error.status, error.code]) {
+        if (typeof value === "number" && value >= 100 && value < 600)
+            return value;
+    }
+    return undefined;
+}
+const isConflict = (e) => httpStatus(e) === 409 || (typeof e === "object" && e !== null && "code" in e && e.code === "DRIVE_ALREADY_EXISTS");
+/** The server answered and refused the request, so it changed nothing. Anything else (5xx, network error, timeout) may have gone through. */
+function isRejected(e) {
+    const status = httpStatus(e);
+    return status !== undefined && status >= 400 && status < 500 && status !== 408;
+}
+function validateMountDrives(mounts, createIfNotExist) {
+    for (const { driveName, create } of mounts) {
+        if (!driveName === !create) {
+            throw new TypeError("Each mountDrives entry needs exactly one of 'driveName' or 'create'.");
+        }
+        if (createIfNotExist && create && !create.name) {
+            throw new TypeError("With createIfNotExist, a new drive in mountDrives needs a name; otherwise every call would create another drive.");
+        }
+    }
+}
+/** Runs tasks with at most `limit` in flight; a freed slot goes straight to the next waiter. */
+function limiter(limit) {
+    let active = 0;
+    const waiting = [];
+    return async (task) => {
+        if (active >= limit)
+            await new Promise(resolve => waiting.push(resolve));
+        else
+            active++;
+        try {
+            return await task();
+        }
+        finally {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                active--;
+        }
+    };
+}
+/**
+ * Drives for one `SandboxInstance.create` call. Looking up or creating drives
+ * (`start`) runs alongside the sandbox creation, at most
+ * `MOUNT_DRIVES_CONCURRENCY` at a time; only mounting waits for both the sandbox
+ * and its drive (`mount`). On failure, drives this call created under a
+ * generated name and did not mount are deleted (`discard`, or `mount` when it
+ * fails); drives under a caller's name are kept and reported.
+ */
+class SandboxDriveSetup {
+    mounts;
+    stopped = false;
+    prepared = [];
+    entries;
+    region;
+    setRegion;
+    /**
+     * `region` is the region the sandbox creation request sends, if any. New
+     * drives are created in it at once; without one they wait for the created
+     * sandbox and use its region.
+     */
+    constructor(mounts, region) {
+        this.mounts = mounts;
+        this.entries = mounts.map(() => ({}));
+        this.region = new Promise(resolve => { this.setRegion = resolve; });
+        if (region)
+            this.setRegion(region);
+    }
+    start() {
+        const limit = limiter(exports.MOUNT_DRIVES_CONCURRENCY);
+        this.prepared = this.mounts.map(async (mount, index) => {
+            // A new drive goes in the sandbox's region, so it waits for it (without holding a slot) if it is not known yet.
+            // Lookups await too, so that entries keep their order in the queue.
+            const region = await (mount.create ? this.region : undefined);
+            return limit(async () => {
+                if (this.stopped)
+                    return undefined;
+                try {
+                    const drive = mount.create ? await this.createDrive(this.entries[index], mount.create, region) : await index_js_1.DriveInstance.get(mount.driveName);
+                    Object.assign(this.entries[index], { name: drive.name, exists: true });
+                    return drive;
+                }
+                catch (e) {
+                    this.stopped = true;
+                    throw e;
+                }
+            });
+        });
+        // Failures surface in mount() or discard().
+        for (const promise of this.prepared)
+            promise.catch(() => { });
+    }
+    /** Create a drive in the sandbox's region; a named one that already exists is reused. */
+    async createDrive(entry, create, region) {
+        if (!region)
+            throw new Error("The sandbox reports no region, so its drives were not created.");
+        const requested = create.region;
+        if (requested && requested !== region) {
+            throw new Error(`Drive region ${requested} does not match the sandbox region ${region}.`);
+        }
+        // Name unnamed drives here so that a create whose response is lost can still be looked up.
+        const name = create.name || `drive-${(0, uuid_1.v4)().replace(/-/g, "").slice(0, 16)}`;
+        entry.name = name;
+        entry.generated = !create.name;
+        try {
+            const drive = await index_js_1.DriveInstance.create({ ...create, name, region });
+            entry.created = true;
+            return drive;
+        }
+        catch (e) {
+            if (isConflict(e)) {
+                // Only a name the caller chose can belong to an existing drive worth reusing.
+                if (!create.name)
+                    throw e;
+                return index_js_1.DriveInstance.get(name);
+            }
+            if (isRejected(e))
+                throw e;
+            // The create may have succeeded server-side: look the drive up by its name.
+            entry.unconfirmed = true;
+            const drive = await index_js_1.DriveInstance.get(name).catch(() => { throw e; });
+            entry.unconfirmed = false;
+            // A generated name is this call's own; a chosen one may be an existing drive, which is never deleted.
+            if (!create.name)
+                entry.created = true;
+            return drive;
+        }
+    }
+    /**
+     * The sandbox could not be created: stop, wait for drives in flight and delete
+     * the ones this call created under a generated name. Returns the error to
+     * throw: `cause` itself, or a `SandboxDriveSetupError` naming drives left in place.
+     */
+    async discard(cause) {
+        this.stopped = true;
+        this.setRegion(undefined);
+        await Promise.allSettled(this.prepared);
+        await this.rollback();
+        const left = this.leftCreated();
+        return left.length ? new SandboxDriveSetupError(undefined, this.leftNames(), left, cause) : cause;
+    }
+    /** Mount each drive as soon as it is ready, then check the sandbox lists the mounts as requested. */
+    async mount(sandbox) {
+        const region = sandbox.spec?.region;
+        this.setRegion(region);
+        const limit = limiter(exports.MOUNT_DRIVES_CONCURRENCY);
+        const requests = [];
+        const results = await Promise.allSettled(this.prepared.map(async (prepared, index) => {
+            try {
+                const drive = await prepared;
+                if (!drive)
+                    return;
+                if (drive.region !== region) {
+                    throw new Error(`Drive ${drive.name} is in ${drive.region}, but the sandbox is in ${region}.`);
+                }
+                const { mountPath, drivePath = "/", readOnly = false } = this.mounts[index];
+                const request = { driveName: drive.name, mountPath, drivePath, readOnly };
+                await limit(async () => {
+                    if (this.stopped)
+                        return;
+                    requests.push(request);
+                    this.entries[index].mounted = true;
+                    await sandbox.drives.mount(request);
+                });
+            }
+            catch (e) {
+                this.stopped = true;
+                throw e;
+            }
+        }));
+        try {
+            const failed = results.find((result) => result.status === "rejected");
+            if (failed)
+                throw failed.reason;
+            // Mounting reports success even if an existing mount at that path keeps a different readOnly, so check.
+            const mounted = await sandbox.drives.list();
+            for (const request of requests) {
+                const actual = mounted.find(mount => cleanPath(mount.mountPath) === cleanPath(request.mountPath));
+                if (actual?.driveName !== request.driveName || cleanPath(actual.drivePath) !== cleanPath(request.drivePath) || (actual.readOnly ?? false) !== request.readOnly) {
+                    throw new Error(`${request.mountPath} is not mounted as requested; see sandbox.drives.list().`);
+                }
+            }
+        }
+        catch (cause) {
+            await this.rollback(sandbox);
+            throw new SandboxDriveSetupError(sandbox, this.leftNames(), this.leftCreated(), cause);
+        }
+    }
+    /**
+     * Delete the drives this call created under a generated name and did not mount.
+     * A drive under a caller's name may already be mounted by a concurrent call that
+     * reused it, so it is kept. Drives left in place are listed in `leftCreated`.
+     */
+    async rollback(sandbox) {
+        const created = this.entries.filter(entry => entry.created && entry.generated && entry.exists);
+        if (sandbox && created.some(entry => entry.mounted)) {
+            // A failed mount call may still have mounted its drive (a lost response), and a
+            // successful one may not have (the path was already mounted): ask the sandbox.
+            try {
+                const mounted = new Set((await sandbox.drives.list()).map(mount => mount.driveName));
+                for (const entry of created)
+                    entry.mounted = mounted.has(entry.name);
+            }
+            catch {
+                // Unknown: keep every drive a mount was attempted for.
+            }
+        }
+        const limit = limiter(exports.MOUNT_DRIVES_CONCURRENCY);
+        await Promise.all(created.filter(entry => !entry.mounted).map(entry => limit(async () => {
+            try {
+                await index_js_1.DriveInstance.delete(entry.name);
+                entry.exists = false;
+            }
+            catch {
+                // Reported through SandboxDriveSetupError.createdDrives.
+            }
+        })));
+    }
+    leftNames() {
+        return this.entries.filter(entry => entry.exists).map(entry => entry.name);
+    }
+    leftCreated() {
+        return this.entries.filter(entry => (entry.created && entry.exists) || entry.unconfirmed).map(entry => entry.name);
+    }
+}
+exports.SandboxDriveSetup = SandboxDriveSetup;

package/dist/cjs/sandbox/preview.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxPreviews = exports.SandboxPreview = exports.SandboxPreviewTokens = exports.SandboxPreviewToken = void 0;
 const index_js_1 = require("../client/index.js");
+const logger_js_1 = require("../common/logger.js");
 function isShorthand(preview) {
     return !("metadata" in preview || "spec" in preview);
 }
@@ -259,7 +260,7 @@ class SandboxPreviews {
         return data;
     }
     async waitForDeletion(previewName, timeoutMs = 10000) {
-        console.log(`Waiting for preview deletion: ${previewName}`);
+        logger_js_1.logger.debug(`Waiting for preview deletion: ${previewName}`);
         const pollInterval = 500; // Poll every 500ms
         const startTime = Date.now();
         while (Date.now() - startTime < timeoutMs) {

package/dist/cjs/sandbox/sandbox.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxInstance = exports.SandboxCreationTimeoutError = exports.MAX_CREATION_TIMEOUT_SECONDS = void 0;
+exports.SandboxInstance = exports.SandboxCreationTimeoutError = exports.SandboxDriveSetupError = exports.MAX_CREATION_TIMEOUT_SECONDS = void 0;
 exports.isCreationTimeoutError = isCreationTimeoutError;
 const index_js_1 = require("../client/index.js");
 const logger_js_1 = require("../common/logger.js");
@@ -42,10 +42,12 @@ const pagination_js_1 = require("../common/pagination.js");
 const settings_js_1 = require("../common/settings.js");
 const index_js_2 = require("./codegen/index.js");
 const index_js_3 = require("./drive/index.js");
+const drift_js_1 = require("./drift.js");
 const index_js_4 = require("./filesystem/index.js");
 const index_js_5 = require("./network/index.js");
 const preview_js_1 = require("./preview.js");
 const index_js_6 = require("./process/index.js");
+const mount_drives_js_1 = require("./mount-drives.js");
 const schedule_js_1 = require("./schedule.js");
 const snapshot_js_1 = require("./snapshot.js");
 const session_js_1 = require("./session.js");
@@ -83,6 +85,8 @@ const CREATE_GATEWAY_TIMEOUT_MAX_POLL_MS = 5_000;
 // client instead of being masked by an edge 504.
 const CREATION_TIMEOUT_HEADER = "X-Blaxel-Creation-Timeout";
 exports.MAX_CREATION_TIMEOUT_SECONDS = 50;
+var mount_drives_js_2 = require("./mount-drives.js");
+Object.defineProperty(exports, "SandboxDriveSetupError", { enumerable: true, get: function () { return mount_drives_js_2.SandboxDriveSetupError; } });
 /**
  * Thrown by SandboxInstance.create / createIfNotExists when the sandbox was
  * not ready within the creation deadline. The control plane has released the
@@ -330,13 +334,39 @@ class SandboxInstance {
         return this;
     }
     static async create(sandbox, options = {}) {
-        const { safe = false, createIfNotExist = false } = options;
-        const { timeout } = validateCreateOptions(options);
+        const { mountDrives = [], createIfNotExist = false } = options;
+        validateCreateOptions(options);
+        (0, mount_drives_js_1.validateMountDrives)(mountDrives, createIfNotExist);
+        const { model, requested } = SandboxInstance.toSandboxModel(sandbox);
+        if (!mountDrives.length)
+            return SandboxInstance.createSandboxInstance(model, requested, options);
+        // Drives are set up alongside the sandbox, in the region this request sends (if it
+        // sends none, the control plane picks one and new drives wait for the sandbox).
+        const drives = new mount_drives_js_1.SandboxDriveSetup(mountDrives, model.spec?.region);
+        drives.start();
+        let instance;
+        try {
+            instance = await SandboxInstance.createSandboxInstance(model, requested, options);
+        }
+        catch (err) {
+            throw await drives.discard(err);
+        }
+        await drives.mount(instance);
+        return instance;
+    }
+    /**
+     * The creation request body, with the SDK's defaults (image, memory, region from BL_REGION) applied,
+     * plus what the caller explicitly asked for (before defaults).
+     */
+    static toSandboxModel(sandbox) {
         // No client-side default name: when the caller omits a name we send the
         // creation without metadata.name so the server can assign one and unnamed
         // creations become eligible for warm sandbox pools (ENG-3931).
         const defaultImage = `blaxel/base-image:latest`;
         const defaultMemory = 4096;
+        // What the caller asked for, read before the defaults below fill the gaps:
+        // createIfNotExists compares only these with the sandbox it gets back.
+        let requested = {};
         // Handle SandboxCreateConfiguration or simple dict with name/image/memory/ports/envs/volumes keys
         if (!sandbox ||
             'name' in sandbox ||
@@ -354,6 +384,7 @@ class SandboxInstance {
             'standbyGracePeriodSeconds' in sandbox) {
             if (!sandbox)
                 sandbox = {};
+            requested = { image: sandbox.image, memory: sandbox.memory, region: sandbox.region, envs: (0, types_js_1.normalizeEnvs)(sandbox.envs) };
             if (!sandbox.image)
                 sandbox.image = defaultImage;
             if (!sandbox.memory)
@@ -400,6 +431,10 @@ class SandboxInstance {
                 sandbox.spec.runtime.expires = expires.toISOString();
             }
         }
+        else {
+            const { region, runtime } = sandbox.spec ?? {};
+            requested = { image: runtime?.image, memory: runtime?.memory, region, envs: runtime?.envs };
+        }
         sandbox = sandbox;
         if (!sandbox.metadata) {
             // Leave name unset so the server assigns one (ENG-3931).
@@ -413,6 +448,11 @@ class SandboxInstance {
         }
         sandbox.spec.runtime.image = sandbox.spec.runtime.image || defaultImage;
         sandbox.spec.runtime.memory = sandbox.spec.runtime.memory || defaultMemory;
+        return { model: sandbox, requested };
+    }
+    static async createSandboxInstance(sandbox, requested, options) {
+        const { safe = false, createIfNotExist = false } = options;
+        const { timeout } = validateCreateOptions(options);
         const edgeDomain = SandboxInstance.edgeDomainForRegion(sandbox.spec?.region);
         // Kick off warming so h2Pool.get() can join it during the API call
         if (edgeDomain && !settings_js_1.settings.disableH2) {
@@ -442,6 +482,8 @@ class SandboxInstance {
                 throw createResult.error;
             }
         }
+        if (createIfNotExist)
+            SandboxInstance.warnOnDrift(requested, data);
         // Inject the H2 session into the config so subsystems can use it
         const config = { ...data, h2Session, h2Domain: settings_js_1.settings.disableH2 ? null : edgeDomain };
         const instance = new SandboxInstance(config);
@@ -679,6 +721,21 @@ class SandboxInstance {
     static async createIfNotExists(sandbox, options = {}) {
         return this.create(sandbox, { ...options, createIfNotExist: true });
     }
+    // createIfNotExists hands back the sandbox already holding the name, whatever
+    // it was created with. Say so when it is not what was asked for; this only
+    // logs and never throws or changes what is returned.
+    static warnOnDrift(requested, existing) {
+        if (!existing)
+            return;
+        try {
+            const drift = (0, drift_js_1.describeDrift)(requested, existing);
+            if (drift.length)
+                console.warn((0, drift_js_1.driftWarning)(existing.metadata?.name, drift));
+        }
+        catch {
+            // Best-effort diagnostics: a failed comparison must not fail the create.
+        }
+    }
     // Poll the record after a create was cut by the edge with a 504 while the
     // control plane is still deploying it. Resolves with the sandbox once it
     // reaches DEPLOYED; throws on FAILED or once the wait budget is spent.

package/dist/cjs/types/sandbox/drift.d.ts

@@ -0,0 +1,30 @@
+import type { Env } from "../client/index.js";
+/** The fields of a create request that are compared with an existing sandbox. A field the caller did not set is not compared. */
+export type RequestedSandbox = {
+    image?: string;
+    memory?: number;
+    region?: string;
+    envs?: Env[];
+};
+type ExistingSandbox = {
+    metadata?: {
+        name?: string;
+    };
+    spec?: {
+        region?: string;
+        runtime?: {
+            image?: string;
+            memory?: number;
+            envs?: Env[];
+        };
+    };
+};
+/**
+ * Describes how an existing sandbox differs from the configuration that was
+ * asked for, one entry per field (image, memory, region, envs). Empty when
+ * nothing differs. A field the existing sandbox does not report is not drift.
+ */
+export declare function describeDrift(requested: RequestedSandbox, existing: ExistingSandbox): string[];
+/** The single warning createIfNotExists logs when the sandbox it returned is not the one that was asked for. */
+export declare function driftWarning(name: string | undefined, drift: string[]): string;
+export {};

package/dist/cjs/types/sandbox/mount-drives.d.ts

@@ -0,0 +1,66 @@
+import type { SandboxInstance } from "./sandbox.js";
+import type { SandboxDriveMountConfiguration } from "./types.js";
+/** Most drive lookups/creations, mounts and deletions in flight at once. */
+export declare const MOUNT_DRIVES_CONCURRENCY = 5;
+/**
+ * Thrown when `mountDrives` could not be set up. Drives this call created
+ * under a name it generated and did not mount are deleted first; a drive
+ * created under a name you chose is never deleted, since a concurrent call may
+ * be using it. `createdDrives` names the drives this call created (or may have
+ * created, when a response was lost) that are left in place.
+ *
+ * - `sandbox` is set when the sandbox is ready: it and the mounts made so far
+ *   are kept. `driveNames` lists the drives this call looked up or created that
+ *   are left in place.
+ * - `sandbox` is undefined when the sandbox could not be created (its error is
+ *   the `cause`) and some drives created for it could not be deleted. When they
+ *   all could, the sandbox's error is thrown as is instead.
+ */
+export declare class SandboxDriveSetupError extends Error {
+    readonly sandbox: SandboxInstance | undefined;
+    readonly driveNames: string[];
+    readonly createdDrives: string[];
+    constructor(sandbox: SandboxInstance | undefined, driveNames: string[], createdDrives: string[], cause: unknown);
+}
+export declare function validateMountDrives(mounts: SandboxDriveMountConfiguration[], createIfNotExist: boolean): void;
+/**
+ * Drives for one `SandboxInstance.create` call. Looking up or creating drives
+ * (`start`) runs alongside the sandbox creation, at most
+ * `MOUNT_DRIVES_CONCURRENCY` at a time; only mounting waits for both the sandbox
+ * and its drive (`mount`). On failure, drives this call created under a
+ * generated name and did not mount are deleted (`discard`, or `mount` when it
+ * fails); drives under a caller's name are kept and reported.
+ */
+export declare class SandboxDriveSetup {
+    private mounts;
+    private stopped;
+    private prepared;
+    private entries;
+    private region;
+    private setRegion;
+    /**
+     * `region` is the region the sandbox creation request sends, if any. New
+     * drives are created in it at once; without one they wait for the created
+     * sandbox and use its region.
+     */
+    constructor(mounts: SandboxDriveMountConfiguration[], region?: string);
+    start(): void;
+    /** Create a drive in the sandbox's region; a named one that already exists is reused. */
+    private createDrive;
+    /**
+     * The sandbox could not be created: stop, wait for drives in flight and delete
+     * the ones this call created under a generated name. Returns the error to
+     * throw: `cause` itself, or a `SandboxDriveSetupError` naming drives left in place.
+     */
+    discard(cause: unknown): Promise<unknown>;
+    /** Mount each drive as soon as it is ready, then check the sandbox lists the mounts as requested. */
+    mount(sandbox: SandboxInstance): Promise<void>;
+    /**
+     * Delete the drives this call created under a generated name and did not mount.
+     * A drive under a caller's name may already be mounted by a concurrent call that
+     * reused it, so it is kept. Drives left in place are listed in `leftCreated`.
+     */
+    private rollback;
+    private leftNames;
+    private leftCreated;
+}

package/dist/cjs/types/sandbox/sandbox.d.ts

@@ -10,7 +10,7 @@ import { SandboxSchedules } from "./schedule.js";
 import { SandboxSnapshotsResource } from "./snapshot.js";
 import { SandboxSessions } from "./session.js";
 import { SandboxSystem } from "./system.js";
-import { SandboxConfiguration, SandboxCreateConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
+import { SandboxConfiguration, SandboxCreateConfiguration, SandboxDriveMountConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
 export type SandboxListQuery = NonNullable<ListSandboxesData["query"]>;
 export type SandboxForkOptions = {
     /** Resource type to fork into. Defaults to "sandbox". */
@@ -66,7 +66,20 @@ export type SandboxCreateOptions = {
      * control plane's default deadline applies.
      */
     timeout?: number;
+    /**
+     * Drives to mount on the sandbox. Drives are looked up or created while the
+     * sandbox is being created (a few at a time), in the region the request sends
+     * (or, without one, in the region the sandbox gets), and each is mounted as
+     * soon as the sandbox and that drive are ready. On failure, unnamed drives
+     * this call created and did not mount are deleted; named ones are kept (a
+     * concurrent call may be using them) and listed in the error. If drive setup
+     * fails the sandbox is kept and a SandboxDriveSetupError is thrown; if the
+     * sandbox cannot be created, its error is thrown (wrapped in a
+     * SandboxDriveSetupError only if a drive created for it is left in place).
+     */
+    mountDrives?: SandboxDriveMountConfiguration[];
 };
+export { SandboxDriveSetupError } from "./mount-drives.js";
 /**
  * Thrown by SandboxInstance.create / createIfNotExists when the sandbox was
  * not ready within the creation deadline. The control plane has released the
@@ -188,6 +201,12 @@ export declare class SandboxInstance {
         interval?: number;
     }): Promise<this>;
     static create(sandbox?: SandboxModel | SandboxCreateConfiguration, options?: SandboxCreateOptions): Promise<SandboxInstance>;
+    /**
+     * The creation request body, with the SDK's defaults (image, memory, region from BL_REGION) applied,
+     * plus what the caller explicitly asked for (before defaults).
+     */
+    private static toSandboxModel;
+    private static createSandboxInstance;
     /**
      * Archive a sandbox: keep its filesystem, stop the sandbox.
      *
@@ -276,6 +295,7 @@ export declare class SandboxInstance {
      * `options` (e.g. `timeout`) are forwarded to `create`.
      */
     static createIfNotExists(sandbox: SandboxModel | SandboxCreateConfiguration, options?: Omit<SandboxCreateOptions, "createIfNotExist">): Promise<SandboxInstance>;
+    private static warnOnDrift;
     private static waitAfterCreateGatewayTimeout;
     static fromSession(session: SessionWithToken): Promise<SandboxInstance>;
 }

package/dist/cjs/types/sandbox/types.d.ts

@@ -1,4 +1,5 @@
 import type http2 from "http2";
+import type { DriveCreateConfiguration } from "../drive/index.js";
 import { Port, Sandbox, SandboxLifecycle, VolumeAttachment, SandboxNetwork } from "../client/types.gen";
 import { PostProcessResponse, ProcessRequest } from "./client";
 export interface SessionCreateOptions {
@@ -38,6 +39,21 @@ export type SandboxUpdateMetadata = {
 export type SandboxUpdateNetwork = {
     network?: SandboxNetwork;
 };
+/**
+ * A drive to mount on the sandbox: `driveName` for a drive that already
+ * exists, `create` for a new one. New drives are created in the sandbox's region.
+ */
+export type SandboxDriveMountConfiguration = {
+    mountPath: string;
+    drivePath?: string;
+    readOnly?: boolean;
+} & ({
+    driveName: string;
+    create?: never;
+} | {
+    create: Omit<DriveCreateConfiguration, "region">;
+    driveName?: never;
+});
 export type SandboxPreviewCreateConfiguration = {
     port: number;
     /** Defaults to preview-<port> within this sandbox. */