@blaxel/core 0.3.13-preview.270 → 0.3.17

package/dist/esm/client/sdk.gen.js

@@ -1616,6 +1616,22 @@ export const updateSandbox = (options) => {
         }
     });
 };
+/**
+ * Archive sandbox
+ * Archives a sandbox. The changes its filesystem accumulated over its image are exported to the archive store, then the sandbox is shut down while its definition is kept, so it can be recreated later with the same disk. Memory and running processes are not preserved, processes are started again from their configuration when the sandbox is unarchived.
+ */
+export const archiveSandbox = (options) => {
+    return (options.client ?? _heyApiClient).post({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/sandboxes/{sandboxName}/archive',
+        ...options
+    });
+};
 /**
  * Fork sandbox
  * Forks a sandbox into a new sandbox or application. When forking to a sandbox, the target must not already exist (409 if it does). When forking to an application, a new revision is added if the app already exists, or a new application is created. This is a WIP endpoint — the full implementation depends on the execution plane.
@@ -1932,6 +1948,38 @@ export const deleteSandboxSnapshot = (options) => {
         ...options
     });
 };
+/**
+ * Restore sandbox from snapshot
+ * Restores a sandbox to one of its own snapshots. The running sandbox is torn down and rebuilt from the snapshot under the same name and URLs, so everything it held since the snapshot was taken is lost unless it was itself snapshotted.
+ */
+export const restoreSandboxSnapshot = (options) => {
+    return (options.client ?? _heyApiClient).post({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/sandboxes/{sandboxName}/snapshots/{snapshotId}/restore',
+        ...options
+    });
+};
+/**
+ * Unarchive sandbox
+ * Recreates an archived sandbox from its archive. The recreated sandbox runs the current generation whatever generation it was archived from, restores the archived filesystem before anything starts, and starts the saved processes again with new process identifiers.
+ */
+export const unarchiveSandbox = (options) => {
+    return (options.client ?? _heyApiClient).post({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/sandboxes/{sandboxName}/unarchive',
+        ...options
+    });
+};
 /**
  * Get sandbox by external ID
  * Returns the most recent non-terminated sandbox matching the given external ID. If no active sandbox is found, returns 404.
@@ -1948,6 +1996,54 @@ export const getSandboxByExternalId = (options) => {
         ...options
     });
 };
+/**
+ * List Workspace Schedule Executions
+ * Returns schedule execution submissions across the workspace, newest first by default. Status describes submission acceptance, not process completion. since and until are inclusive RFC 3339 bounds on creation time.
+ */
+export const listScheduleExecutions = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/schedule-executions',
+        ...options
+    });
+};
+/**
+ * List Workspace Schedules
+ * Returns schedule definitions across the workspace, newest first by default.
+ */
+export const listSchedules = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/schedules',
+        ...options
+    });
+};
+/**
+ * Get Sandbox Scheduling Metrics
+ * Returns active sandbox and scheduling metrics for a UTC minute window. since is inclusive and until is exclusive. The default window is the last 24 hours and the maximum is 7 days. Execution status describes submission acceptance, not process completion. Execution totals begin accumulating when metrics collection is enabled and can lag recent firings briefly.
+ */
+export const getSandboxScheduleMetrics = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/schedules/metrics',
+        ...options
+    });
+};
 /**
  * List service accounts
  * Returns all service accounts in the workspace. Service accounts are machine identities for external systems to authenticate with Blaxel via OAuth or API keys.

package/dist/esm/common/settings.js

@@ -24,8 +24,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.13-preview.270";
-const BUILD_COMMIT = "615fb5551f22447c530bcaef346d68dc79590758";
+const BUILD_VERSION = "0.3.17";
+const BUILD_COMMIT = "3e03a965bdb4d5aa9d2c5105cd1f4d8018198df2";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-28";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/esm/common/shell.js

@@ -0,0 +1,15 @@
+/**
+ * Quote a string so a POSIX shell reads it as one literal argument.
+ *
+ * The sandbox process API accepts a single command string, which the server
+ * runs as `sh -c <command>`. Any value interpolated into that string is parsed
+ * by the shell, so an unquoted path containing `;`, `|`, `&&`, `$()`, backticks
+ * or `>` would execute as its own command. Single quotes suppress every form of
+ * shell expansion; the only character they cannot contain is a single quote
+ * itself, which is closed, escaped, and reopened.
+ *
+ * This is the TypeScript equivalent of Python's `shlex.quote`.
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/esm/sandbox/filesystem/filesystem.js

@@ -2,12 +2,13 @@ import { fs } from "../../common/node.js";
 import { settings } from "../../common/settings.js";
 import { withUploadSlot } from "../../common/h2fetch.js";
 import { isTransientResetError, retryOnTransientReset } from "../../common/transient-retry.js";
+import { shellQuote } from "../../common/shell.js";
 import { SandboxAction } from "../action.js";
 import { deleteFilesystemByPath, deleteFilesystemMultipartByUploadIdAbort, getFilesystemByPath, getFilesystemContentSearchByPath, getFilesystemFindByPath, getFilesystemSearchByPath, getWatchFilesystemByPath, postFilesystemMultipartByUploadIdComplete, postFilesystemMultipartInitiateByPath, putFilesystemByPath, putFilesystemMultipartByUploadIdPart } from "../client/index.js";
 // Multipart upload constants
 const MULTIPART_THRESHOLD = 5 * 1024 * 1024; // 5MB
 const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB per part
-const MAX_PARALLEL_UPLOADS = 3; // Number of parallel part uploads
+const MAX_PARALLEL_UPLOADS = 3; // Maximum workers when the H2 upload cap is disabled
 // The transient-reset classifier and retry loop live in
 // common/transient-retry.ts, shared with the idempotent sandbox-op retry
 // (read/list/etc.) so every path judges "transient" identically. These aliases
@@ -343,8 +344,10 @@ export class SandboxFileSystem extends SandboxAction {
         });
     }
     async cp(source, destination, { maxWait = 180000 } = {}) {
+        // Quote both paths so the shell that runs this command treats them as
+        // single literal arguments instead of interpreting metacharacters in them.
         let process = await this.process.exec({
-            command: `cp -r ${source} ${destination}`,
+            command: `cp -r ${shellQuote(source)} ${shellQuote(destination)}`,
         });
         process = await this.process.wait(process.pid, { maxWait, interval: 100 });
         if (process.status === "failed") {
@@ -498,11 +501,19 @@ export class SandboxFileSystem extends SandboxAction {
             // no h2Domain the parts go over globalThis.fetch on separate connections,
             // so the shared-connection cap does not apply.
             const h2Domain = this.sandbox?.h2Domain;
-            // Upload parts in batches for parallel processing
-            for (let i = 0; i < numParts; i += MAX_PARALLEL_UPLOADS) {
-                const batch = [];
-                for (let j = 0; j < MAX_PARALLEL_UPLOADS && i + j < numParts; j++) {
-                    const partNumber = i + j + 1;
+            // Keep a bounded worker queue full instead of waiting at fixed batch
+            // boundaries. The upload gate remains authoritative across files; its
+            // default of 2 also bounds this queue on H2.
+            const h2UploadLimit = h2Domain ? settings.maxConcurrentUploadH2Requests : 0;
+            const workerCount = Math.min(numParts, h2UploadLimit > 0 ? Math.min(MAX_PARALLEL_UPLOADS, h2UploadLimit) : MAX_PARALLEL_UPLOADS);
+            let nextPartNumber = 1;
+            let stopped = false;
+            let uploadError;
+            const uploadNextPart = async () => {
+                while (!stopped) {
+                    const partNumber = nextPartNumber++;
+                    if (partNumber > numParts)
+                        return;
                     const start = (partNumber - 1) * CHUNK_SIZE;
                     const end = Math.min(start + CHUNK_SIZE, size);
                     const chunk = blob.slice(start, end);
@@ -510,11 +521,20 @@ export class SandboxFileSystem extends SandboxAction {
                     // concurrent part streams, not retry sequences; freed during backoff.
                     const doPart = () => this.uploadPart(uploadId, partNumber, chunk);
                     const partWithSlot = h2Domain ? () => withUploadSlot(h2Domain, doPart) : doPart;
-                    batch.push(retryOnTransient(partWithSlot));
+                    try {
+                        parts.push(await retryOnTransient(partWithSlot));
+                    }
+                    catch (error) {
+                        if (!stopped) {
+                            stopped = true;
+                            uploadError = error;
+                        }
+                    }
                 }
-                // Wait for batch to complete
-                const batchResults = await Promise.all(batch);
-                parts.push(...batchResults);
+            };
+            await Promise.all(Array.from({ length: workerCount }, () => uploadNextPart()));
+            if (stopped) {
+                throw uploadError;
             }
             // Sort parts by partNumber to ensure correct order
             parts.sort((a, b) => (a.partNumber ?? 0) - (b.partNumber ?? 0));

package/dist/esm/sandbox/filesystem/filesystem.test.js

@@ -1,9 +1,61 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { settings } from "../../common/settings.js";
 import { SandboxFileSystem } from "./filesystem.js";
 const waitForPartUpload = () => new Promise((resolve) => setTimeout(resolve, 5));
+function deferred() {
+    let resolve;
+    const promise = new Promise((resolvePromise) => {
+        resolve = resolvePromise;
+    });
+    return { promise, resolve };
+}
 describe("SandboxFileSystem multipart upload", () => {
-    it("limits concurrent part uploads", async () => {
+    afterEach(() => {
+        delete settings.config.maxConcurrentUploadH2Requests;
+        delete settings.config.fsPartRetries;
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it("keeps an H2 upload slot busy across former batch boundaries for 100 MiB", async () => {
+        settings.config.maxConcurrentUploadH2Requests = 2;
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        filesystem.sandbox = { h2Domain: "eng-3585.test" };
+        const started = [deferred(), deferred(), deferred(), deferred()];
+        const release = [deferred(), deferred(), deferred(), deferred()];
+        let completedParts = [];
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-1" });
+        filesystem.uploadPart = async (_uploadId, partNumber) => {
+            if (partNumber <= 4) {
+                started[partNumber - 1].resolve();
+                await release[partNumber - 1].promise;
+            }
+            return { partNumber, etag: `etag-${partNumber}` };
+        };
+        filesystem.completeMultipartUpload = (_uploadId, parts) => {
+            completedParts = parts;
+            return Promise.resolve({ message: "ok" });
+        };
+        filesystem.abortMultipartUpload = () => Promise.resolve({ message: "aborted" });
+        const upload = filesystem.uploadWithMultipart("/tmp/large-file.bin", { size: 100 * 1024 * 1024, slice: () => ({}) });
+        await Promise.all([started[0].promise, started[1].promise]);
+        release[0].resolve();
+        await started[2].promise;
+        release[2].resolve();
+        const crossedBatchBoundary = await Promise.race([
+            started[3].promise.then(() => true),
+            new Promise((resolve) => setTimeout(() => resolve(false), 25)),
+        ]);
+        release[1].resolve();
+        await started[3].promise;
+        release[3].resolve();
+        await upload;
+        expect(crossedBatchBoundary).toBe(true);
+        expect(completedParts).toHaveLength(20);
+    });
+    it("limits concurrent H2 part uploads to the existing cap", async () => {
+        settings.config.maxConcurrentUploadH2Requests = 2;
         const filesystem = Object.create(SandboxFileSystem.prototype);
+        filesystem.sandbox = { h2Domain: "concurrency.test" };
         let inFlight = 0;
         let maxInFlight = 0;
         const uploadedParts = [];
@@ -24,8 +76,161 @@ describe("SandboxFileSystem multipart upload", () => {
         filesystem.abortMultipartUpload = () => Promise.resolve({ message: "aborted" });
         const blob = new Blob([new Uint8Array(16 * 1024 * 1024)]);
         await filesystem.uploadWithMultipart("/tmp/large-file.bin", blob);
-        expect(maxInFlight).toBeLessThanOrEqual(3);
+        expect(maxInFlight).toBe(2);
         expect(uploadedParts.sort((a, b) => a - b)).toEqual([1, 2, 3, 4]);
         expect(completedParts.map((part) => part.partNumber)).toEqual([1, 2, 3, 4]);
     });
+    it("uploads every byte exactly once across chunk boundaries", async () => {
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        const partSize = 5 * 1024 * 1024;
+        const source = new Uint8Array(partSize + 17);
+        for (let index = 0; index < source.length; index++) {
+            source[index] = index % 251;
+        }
+        const uploadedChunks = new Map();
+        let completedParts = [];
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-bytes" });
+        filesystem.uploadPart = async (_uploadId, partNumber, fileBlob) => {
+            uploadedChunks.set(partNumber, new Uint8Array(await fileBlob.arrayBuffer()));
+            return { partNumber, etag: `etag-${partNumber}` };
+        };
+        filesystem.completeMultipartUpload = (_uploadId, parts) => {
+            completedParts = parts;
+            return Promise.resolve({ message: "ok" });
+        };
+        filesystem.abortMultipartUpload = () => Promise.resolve({ message: "aborted" });
+        await filesystem.uploadWithMultipart("/tmp/bytes.bin", new Blob([source]));
+        const received = new Uint8Array(source.length);
+        let offset = 0;
+        for (const partNumber of [1, 2]) {
+            const chunk = uploadedChunks.get(partNumber);
+            expect(chunk).toBeDefined();
+            received.set(chunk, offset);
+            offset += chunk.length;
+        }
+        let mismatch = -1;
+        for (let index = 0; index < source.length; index++) {
+            if (received[index] !== source[index]) {
+                mismatch = index;
+                break;
+            }
+        }
+        expect([...uploadedChunks.values()].map((chunk) => chunk.length)).toEqual([partSize, 17]);
+        expect(offset).toBe(source.length);
+        expect(mismatch).toBe(-1);
+        expect(completedParts.map((part) => part.partNumber)).toEqual([1, 2]);
+    });
+    it("retries a transient part failure without duplicating completed parts", async () => {
+        vi.useFakeTimers();
+        vi.spyOn(Math, "random").mockReturnValue(0);
+        settings.config.fsPartRetries = 1;
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        const attempts = new Map();
+        let completedParts = [];
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-retry" });
+        filesystem.uploadPart = (_uploadId, partNumber) => {
+            const attempt = (attempts.get(partNumber) ?? 0) + 1;
+            attempts.set(partNumber, attempt);
+            if (partNumber === 1 && attempt === 1) {
+                return Promise.reject(Object.assign(new Error("connection reset"), { code: "ECONNRESET" }));
+            }
+            return Promise.resolve({ partNumber, etag: `etag-${partNumber}` });
+        };
+        filesystem.completeMultipartUpload = (_uploadId, parts) => {
+            completedParts = parts;
+            return Promise.resolve({ message: "ok" });
+        };
+        filesystem.abortMultipartUpload = () => Promise.resolve({ message: "aborted" });
+        const upload = filesystem.uploadWithMultipart("/tmp/retry.bin", new Blob([new Uint8Array(6 * 1024 * 1024)]));
+        await vi.runAllTimersAsync();
+        await upload;
+        expect(Object.fromEntries(attempts)).toEqual({ 1: 2, 2: 1 });
+        expect(completedParts.map((part) => part.partNumber)).toEqual([1, 2]);
+    });
+    it("stops assigning queued parts after a part failure", async () => {
+        settings.config.maxConcurrentUploadH2Requests = 2;
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        filesystem.sandbox = { h2Domain: "cancellation.test" };
+        const releaseFirstPart = deferred();
+        const secondPartStarted = deferred();
+        const failure = new Error("part 2 failed");
+        const startedParts = [];
+        const events = [];
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-cancel" });
+        filesystem.uploadPart = async (_uploadId, partNumber) => {
+            startedParts.push(partNumber);
+            if (partNumber === 1) {
+                await releaseFirstPart.promise;
+                events.push("part-1-finished");
+                return { partNumber, etag: "etag-1" };
+            }
+            secondPartStarted.resolve();
+            events.push("part-2-failed");
+            throw failure;
+        };
+        filesystem.completeMultipartUpload = () => {
+            throw new Error("completion must not run");
+        };
+        filesystem.abortMultipartUpload = () => {
+            events.push("aborted");
+            return Promise.resolve({ message: "aborted" });
+        };
+        const upload = filesystem.uploadWithMultipart("/tmp/cancel.bin", new Blob([new Uint8Array(16 * 1024 * 1024)]));
+        await secondPartStarted.promise;
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        releaseFirstPart.resolve();
+        await expect(upload).rejects.toBe(failure);
+        expect(startedParts).toEqual([1, 2]);
+        expect(events).toEqual(["part-2-failed", "part-1-finished", "aborted"]);
+    });
+    it("keeps sliced part data bounded by the active worker count", async () => {
+        settings.config.maxConcurrentUploadH2Requests = 2;
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        filesystem.sandbox = { h2Domain: "memory.test" };
+        let unsettledSlices = 0;
+        let maxUnsettledSlices = 0;
+        let totalSlices = 0;
+        const fakeBlob = {
+            size: 100 * 1024 * 1024,
+            slice(start, end) {
+                totalSlices += 1;
+                unsettledSlices += 1;
+                maxUnsettledSlices = Math.max(maxUnsettledSlices, unsettledSlices);
+                return { size: end - start };
+            },
+        };
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-memory" });
+        filesystem.uploadPart = async (_uploadId, partNumber) => {
+            await waitForPartUpload();
+            unsettledSlices -= 1;
+            return { partNumber, etag: `etag-${partNumber}` };
+        };
+        filesystem.completeMultipartUpload = () => Promise.resolve({ message: "ok" });
+        filesystem.abortMultipartUpload = () => Promise.resolve({ message: "aborted" });
+        await filesystem.uploadWithMultipart("/tmp/100mb.bin", fakeBlob);
+        expect(totalSlices).toBe(20);
+        expect(maxUnsettledSlices).toBe(2);
+        expect(unsettledSlices).toBe(0);
+    });
+    it("aborts an abandoned multipart upload and preserves the part failure", async () => {
+        settings.config.maxConcurrentUploadH2Requests = 1;
+        const filesystem = Object.create(SandboxFileSystem.prototype);
+        filesystem.sandbox = { h2Domain: "cleanup.test" };
+        const partFailure = new Error("part failed");
+        const abortFailure = new Error("abort failed");
+        const aborts = [];
+        const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+        filesystem.initiateMultipartUpload = () => Promise.resolve({ uploadId: "upload-cleanup" });
+        filesystem.uploadPart = () => Promise.reject(partFailure);
+        filesystem.completeMultipartUpload = () => {
+            throw new Error("completion must not run");
+        };
+        filesystem.abortMultipartUpload = (uploadId) => {
+            aborts.push(uploadId);
+            return Promise.reject(abortFailure);
+        };
+        await expect(filesystem.uploadWithMultipart("/tmp/cleanup.bin", new Blob([new Uint8Array(6 * 1024 * 1024)]))).rejects.toBe(partFailure);
+        expect(aborts).toEqual(["upload-cleanup"]);
+        expect(consoleError).toHaveBeenCalledWith("Failed to abort multipart upload:", abortFailure);
+    });
 });

package/dist/esm/sandbox/sandbox.js

@@ -1,4 +1,4 @@
-import { createSandbox, createSandboxSnapshot, deleteSandbox, deleteSandboxSnapshot, forkSandbox, getSandbox, getSandboxByExternalId, listSandboxes, listSandboxSnapshots, updateSandbox } from "../client/index.js";
+import { archiveSandbox, createSandbox, createSandboxSnapshot, deleteSandbox, deleteSandboxSnapshot, forkSandbox, getSandbox, getSandboxByExternalId, listSandboxes, listSandboxSnapshots, restoreSandboxSnapshot, unarchiveSandbox, updateSandbox } from "../client/index.js";
 import { logger } from "../common/logger.js";
 import { backoffDelayMs } from "../common/transient-retry.js";
 import { createPaginatedList } from "../common/pagination.js";
@@ -31,6 +31,23 @@ const TRANSIENT_SANDBOX_STATUSES = new Set([
 ]);
 const TRANSIENT_STATUS_MAX_WAIT_MS = 30_000;
 const TRANSIENT_STATUS_POLL_MS = 500;
+// Archiving a filesystem, and restoring it, take as long as that filesystem is
+// big — minutes for a few gigabytes.
+const ARCHIVE_MAX_WAIT_MS = 1_800_000;
+const ARCHIVE_WAIT_POLL_MS = 2_000;
+// An archive is done when the sandbox is ARCHIVED; it is still under way while
+// the record holds one of these.
+const ARCHIVING_STATUSES = new Set(["ARCHIVING"]);
+// A restore is done when the sandbox is DEPLOYED again; the instance is recreated
+// before the archived filesystem is written back over its image.
+const UNARCHIVING_STATUSES = new Set(["UNARCHIVING", "DEPLOYING", "BUILDING", "UPLOADING"]);
+// The status the sandbox holds before the operation moves it, tolerated only
+// while the operation is starting: an archive that fails hands the sandbox back
+// as DEPLOYED and a restore that fails leaves it ARCHIVED, so reading the entry
+// status once the operation has begun means it is over, not still running.
+const ARCHIVE_ENTRY_STATUS = "DEPLOYED";
+const UNARCHIVE_ENTRY_STATUS = "ARCHIVED";
+const ARCHIVE_ENTRY_MAX_WAIT_MS = 30_000;
 // A create that outlives the edge's 60s origin-read timeout gets a 504 from
 // CloudFront while the control plane keeps deploying the sandbox for up to
 // 300s (ENG-3662 timeout ladder inversion). The 504 body is edge HTML with no
@@ -170,6 +187,24 @@ export class SandboxInstance {
             throwOnError: true,
         });
     }
+    /**
+     * Restore this sandbox to one of its own snapshots. The sandbox keeps its
+     * name, its URLs and its previews: the running instance is torn down and
+     * rebuilt from the snapshot, so everything written since it was taken is
+     * lost unless it was snapshotted too.
+     *
+     * The restore is asked for without waiting on the guest, the same way a fork
+     * is: connections to a sandbox still resuming are retried by the gateway.
+     *
+     * @param snapshotId - ID of the snapshot to restore this sandbox to.
+     */
+    async restore(snapshotId) {
+        const { data } = await restoreSandboxSnapshot({
+            path: { sandboxName: this.metadata.name, snapshotId },
+            throwOnError: true,
+        });
+        return data;
+    }
     /**
      * Fork this sandbox into a new sandbox or application.
      *
@@ -318,6 +353,95 @@ export class SandboxInstance {
         }
         return instance;
     }
+    /**
+     * Archive a sandbox: keep its filesystem, stop the sandbox.
+     *
+     * The filesystem changes made over the image are exported to the archive store
+     * and the sandbox is shut down; memory and running processes are lost, and the
+     * saved processes start again from their configuration when the sandbox is
+     * unarchived. The export runs in the background: this waits until the sandbox
+     * is ARCHIVED, pass `{ wait: false }` to return as soon as it is launched.
+     */
+    static async archive(sandboxName, options = {}) {
+        const { data } = await archiveSandbox({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "ARCHIVED", ARCHIVING_STATUSES, ARCHIVE_ENTRY_STATUS, "archive", options);
+    }
+    /**
+     * Archive this sandbox: keep its filesystem, stop the sandbox.
+     *
+     * @see SandboxInstance.archive
+     */
+    async archive(options = {}) {
+        const instance = await SandboxInstance.archive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    /**
+     * Recreate an archived sandbox from its archive.
+     *
+     * The sandbox is started again from its image, and the archived filesystem is
+     * written back over it. The sandbox answers, and its terminal is reachable, while the archived
+     * filesystem is written back over its image. This waits until the restore is
+     * done and the saved processes are running again; pass `{ wait: false }` to
+     * return while the sandbox is still UNARCHIVING.
+     */
+    static async unarchive(sandboxName, options = {}) {
+        const { data } = await unarchiveSandbox({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "DEPLOYED", UNARCHIVING_STATUSES, UNARCHIVE_ENTRY_STATUS, "unarchive", options);
+    }
+    /**
+     * Recreate this sandbox from its archive.
+     *
+     * @see SandboxInstance.unarchive
+     */
+    async unarchive(options = {}) {
+        const instance = await SandboxInstance.unarchive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    // The subsystems (fs, process, previews, ...) hold the configuration object
+    // this instance was built with, so a refresh writes into it rather than
+    // replacing it. Anything the read did not carry, the forced URL of a session
+    // above all, is kept.
+    refreshFrom(instance) {
+        Object.assign(this.sandbox, instance.sandbox);
+    }
+    static async waitForArchiveStatus(sandboxName, launched, target, pending, entry, action, { wait = true, maxWait = ARCHIVE_MAX_WAIT_MS, interval = ARCHIVE_WAIT_POLL_MS }) {
+        if (!wait || launched.status === target) {
+            return SandboxInstance.attachH2Session(new SandboxInstance(launched));
+        }
+        const deadline = Date.now() + maxWait;
+        // The status the sandbox is given back at is tolerated while the operation
+        // turns into a status change, but never past the wait the caller asked for.
+        const entryDeadline = Date.now() + Math.min(ARCHIVE_ENTRY_MAX_WAIT_MS, maxWait);
+        let started = false;
+        for (;;) {
+            await new Promise((resolve) => setTimeout(resolve, interval));
+            const instance = await SandboxInstance.get(sandboxName);
+            const status = instance.status;
+            if (status === target) {
+                return instance;
+            }
+            if (pending.has(status ?? "")) {
+                started = true;
+            }
+            else if (status === entry && !started && Date.now() < entryDeadline) {
+                continue;
+            }
+            if (!pending.has(status ?? "")) {
+                throw new Error(`Sandbox ${sandboxName} is ${status} while it should ${action}`);
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Sandbox ${sandboxName} is still ${status} after waiting ${Math.round(maxWait / 1000)}s for it to ${action}`);
+            }
+        }
+    }
     static async get(sandboxName) {
         const { data } = await getSandbox({
             path: {