langsmith 0.5.18 → 0.5.20

package/dist/experimental/sandbox/client.js

@@ -7,6 +7,27 @@ import { AsyncCaller } from "../../utils/async_caller.js";
 import { Sandbox } from "./sandbox.js";
 import { LangSmithResourceCreationError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, } from "./errors.js";
 import { handleClientHttpError, handleConflictError, handlePoolError, handleResourceInUseError, handleSandboxCreationError, handleVolumeCreationError, validateTtl, } from "./helpers.js";
+/**
+ * Sleep that can be interrupted by an AbortSignal.
+ * Resolves after `ms` milliseconds or rejects immediately if the signal fires.
+ */
+function sleepWithSignal(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * Get the default sandbox API endpoint from environment.
  *
@@ -50,6 +71,8 @@ function getDefaultApiKey() {
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 export class SandboxClient {
     constructor(config = {}) {
@@ -110,6 +133,25 @@ export class SandboxClient {
     getApiKey() {
         return this._apiKey;
     }
+    /**
+     * JSON POST helper. Sends JSON body, checks response status,
+     * and returns the Response for further processing.
+     * Throws on non-ok responses via handleClientHttpError.
+     * Callers can add specific status checks (e.g. 404) before calling this.
+     * @internal
+     */
+    async _postJson(url, body, options) {
+        const response = await this._fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+        return response;
+    }
     // =========================================================================
     // Volume Operations
     // =========================================================================
@@ -535,14 +577,25 @@ export class SandboxClient {
      * ```
      */
     async createSandbox(templateName, options = {}) {
-        const { name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, } = options;
+        const { snapshotId, name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, vCpus, memBytes, fsCapacityBytes, } = options;
+        if (!templateName && !snapshotId) {
+            throw new Error("Either templateName or snapshotId is required");
+        }
+        if (templateName && snapshotId) {
+            throw new Error("Cannot specify both templateName and snapshotId");
+        }
         validateTtl(ttlSeconds, "ttlSeconds");
         validateTtl(idleTtlSeconds, "idleTtlSeconds");
         const url = `${this._baseUrl}/boxes`;
         const payload = {
-            template_name: templateName,
             wait_for_ready: waitForReady,
         };
+        if (templateName) {
+            payload.template_name = templateName;
+        }
+        if (snapshotId) {
+            payload.snapshot_id = snapshotId;
+        }
         if (waitForReady) {
             payload.timeout = timeout;
         }
@@ -555,6 +608,15 @@ export class SandboxClient {
         if (idleTtlSeconds !== undefined) {
             payload.idle_ttl_seconds = idleTtlSeconds;
         }
+        if (vCpus !== undefined) {
+            payload.vcpus = vCpus;
+        }
+        if (memBytes !== undefined) {
+            payload.mem_bytes = memBytes;
+        }
+        if (fsCapacityBytes !== undefined) {
+            payload.fs_capacity_bytes = fsCapacityBytes;
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -577,9 +639,9 @@ export class SandboxClient {
      * @returns Sandbox.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandbox(name) {
+    async getSandbox(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -674,9 +736,9 @@ export class SandboxClient {
      * @returns ResourceStatus with status and optional status_message.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandboxStatus(name) {
+    async getSandboxStatus(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -706,21 +768,182 @@ export class SandboxClient {
      * ```
      */
     async waitForSandbox(name, options = {}) {
-        const { timeout = 120, pollInterval = 1.0 } = options;
+        const { timeout = 120, pollInterval = 1.0, signal } = options;
         const deadline = Date.now() + timeout * 1000;
         let lastStatus = "provisioning";
         while (Date.now() < deadline) {
-            const statusResult = await this.getSandboxStatus(name);
+            signal?.throwIfAborted();
+            const statusResult = await this.getSandboxStatus(name, { signal });
             lastStatus = statusResult.status;
             if (statusResult.status === "ready") {
-                return this.getSandbox(name);
+                return this.getSandbox(name, { signal });
             }
             if (statusResult.status === "failed") {
                 throw new LangSmithResourceCreationError(statusResult.status_message ?? `Sandbox '${name}' creation failed`, "sandbox");
             }
-            // Wait before polling again
-            await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+            // Wait before polling again, capped to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
         }
         throw new LangSmithResourceTimeoutError(`Sandbox '${name}' did not become ready within ${timeout}s`, "sandbox", lastStatus);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * @param name - Sandbox name.
+     * @param options - Options with timeout.
+     * @returns Sandbox in "ready" status.
+     */
+    async startSandbox(name, options = {}) {
+        const { timeout = 120, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        await this._postJson(url, {}, { signal });
+        return this.waitForSandbox(name, { timeout, signal });
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     *
+     * @param name - Sandbox name.
+     */
+    async stopSandbox(name) {
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        await this._postJson(url, {});
+    }
+    // =========================================================================
+    // Snapshot Operations
+    // =========================================================================
+    /**
+     * Build a snapshot from a Docker image.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param name - Snapshot name.
+     * @param dockerImage - Docker image to build from (e.g., "python:3.12-slim").
+     * @param fsCapacityBytes - Filesystem capacity in bytes.
+     * @param options - Additional options (registry credentials, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
+        const { registryId, registryUrl, registryUsername, registryPassword, timeout = 60, signal, } = options;
+        const url = `${this._baseUrl}/snapshots`;
+        const payload = {
+            name,
+            docker_image: dockerImage,
+            fs_capacity_bytes: fsCapacityBytes,
+        };
+        if (registryId !== undefined) {
+            payload.registry_id = registryId;
+        }
+        if (registryUrl !== undefined) {
+            payload.registry_url = registryUrl;
+        }
+        if (registryUsername !== undefined) {
+            payload.registry_username = registryUsername;
+        }
+        if (registryPassword !== undefined) {
+            payload.registry_password = registryPassword;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Capture a snapshot from a running sandbox.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param sandboxName - Name of the sandbox to capture from.
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(sandboxName, name, options = {}) {
+        const { checkpoint, timeout = 60, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const payload = { name };
+        if (checkpoint !== undefined) {
+            payload.checkpoint = checkpoint;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Get a snapshot by ID.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @returns Snapshot.
+     */
+    async getSnapshot(snapshotId, options) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { signal: options?.signal });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new LangSmithResourceNotFoundError(`Snapshot '${snapshotId}' not found`, "snapshot");
+            }
+            await handleClientHttpError(response);
+        }
+        return (await response.json());
+    }
+    /**
+     * List all snapshots.
+     *
+     * @returns List of Snapshots.
+     */
+    async listSnapshots() {
+        const url = `${this._baseUrl}/snapshots`;
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+        const data = await response.json();
+        return (data.snapshots ?? []);
+    }
+    /**
+     * Delete a snapshot.
+     *
+     * @param snapshotId - Snapshot UUID.
+     */
+    async deleteSnapshot(snapshotId) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { method: "DELETE" });
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+    }
+    /**
+     * Poll until a snapshot reaches "ready" or "failed" status.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Snapshot in "ready" status.
+     */
+    async waitForSnapshot(snapshotId, options = {}) {
+        const { timeout = 300, pollInterval = 2.0, signal } = options;
+        const deadline = Date.now() + timeout * 1000;
+        let lastStatus = "building";
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            const snapshot = await this.getSnapshot(snapshotId, { signal });
+            lastStatus = snapshot.status;
+            if (snapshot.status === "ready") {
+                return snapshot;
+            }
+            if (snapshot.status === "failed") {
+                throw new LangSmithResourceCreationError(snapshot.status_message ?? `Snapshot '${snapshotId}' build failed`, "snapshot");
+            }
+            // Cap sleep to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
+        }
+        throw new LangSmithResourceTimeoutError(`Snapshot '${snapshotId}' did not become ready within ${timeout}s`, "snapshot", lastStatus);
+    }
 }

package/dist/experimental/sandbox/index.cjs

@@ -25,9 +25,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.CommandHandle = exports.Sandbox = exports.SandboxClient = void 0;
-// Emit warning on import (alpha feature)
-console.warn("langsmith/experimental/sandbox is in alpha. " +
-    "This feature is experimental, and breaking changes are expected.");
 // Main classes
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_js_1.SandboxClient; } });

package/dist/experimental/sandbox/index.d.ts

@@ -25,5 +25,5 @@
 export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";
 export { CommandHandle } from "./command_handle.js";
-export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceSpec, ResourceStatus, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
+export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceSpec, ResourceStatus, Snapshot, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, CreateSnapshotOptions, CaptureSnapshotOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
 export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/experimental/sandbox/index.js

@@ -22,9 +22,6 @@
  *
  * @packageDocumentation
  */
-// Emit warning on import (alpha feature)
-console.warn("langsmith/experimental/sandbox is in alpha. " +
-    "This feature is experimental, and breaking changes are expected.");
 // Main classes
 export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";

package/dist/experimental/sandbox/sandbox.cjs

@@ -25,6 +25,8 @@ const ws_execute_js_1 = require("./ws_execute.cjs");
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 class Sandbox {
     /** @internal */
@@ -50,7 +52,7 @@ class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Provisioning status ("provisioning", "ready", "failed"). */
+        /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
         Object.defineProperty(this, "status", {
             enumerable: true,
             configurable: true,
@@ -106,6 +108,34 @@ class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Snapshot ID used to create this sandbox. */
+        Object.defineProperty(this, "snapshot_id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Number of vCPUs allocated. */
+        Object.defineProperty(this, "vCpus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Memory allocation in bytes. */
+        Object.defineProperty(this, "mem_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Root filesystem capacity in bytes. */
+        Object.defineProperty(this, "fs_capacity_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -123,6 +153,10 @@ class Sandbox {
         this.ttl_seconds = data.ttl_seconds;
         this.idle_ttl_seconds = data.idle_ttl_seconds;
         this.expires_at = data.expires_at;
+        this.snapshot_id = data.snapshot_id;
+        this.vCpus = data.vcpus;
+        this.mem_bytes = data.mem_bytes;
+        this.fs_capacity_bytes = data.fs_capacity_bytes;
         this._client = client;
     }
     /**
@@ -337,5 +371,35 @@ class Sandbox {
     async delete() {
         await this._client.deleteSandbox(this.name);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    async start(options = {}) {
+        const refreshed = await this._client.startSandbox(this.name, options);
+        this.status = refreshed.status;
+        this.dataplane_url = refreshed.dataplane_url;
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    async stop() {
+        await this._client.stopSandbox(this.name);
+        this.status = "stopped";
+        this.dataplane_url = undefined;
+    }
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(name, options = {}) {
+        return this._client.captureSnapshot(this.name, name, options);
+    }
 }
 exports.Sandbox = Sandbox;

package/dist/experimental/sandbox/sandbox.d.ts

@@ -1,7 +1,7 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import type { ExecutionResult, RunOptions } from "./types.js";
+import type { CaptureSnapshotOptions, ExecutionResult, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
 import { CommandHandle } from "./command_handle.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -20,16 +20,18 @@ import { CommandHandle } from "./command_handle.js";
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 export declare class Sandbox {
     /** Display name (can be updated). */
     readonly name: string;
     /** Name of the template used to create this sandbox. */
-    readonly template_name: string;
+    readonly template_name?: string;
     /** URL for data plane operations (file I/O, command execution). */
-    readonly dataplane_url?: string;
-    /** Provisioning status ("provisioning", "ready", "failed"). */
-    readonly status?: string;
+    dataplane_url?: string;
+    /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
+    status?: string;
     /** Human-readable status message (e.g., error details when failed). */
     readonly status_message?: string;
     /** Unique identifier (UUID). Remains constant even if name changes. */
@@ -44,6 +46,14 @@ export declare class Sandbox {
     readonly idle_ttl_seconds?: number;
     /** Computed expiration timestamp when a TTL is active. */
     readonly expires_at?: string;
+    /** Snapshot ID used to create this sandbox. */
+    readonly snapshot_id?: string;
+    /** Number of vCPUs allocated. */
+    readonly vCpus?: number;
+    /** Memory allocation in bytes. */
+    readonly mem_bytes?: number;
+    /** Root filesystem capacity in bytes. */
+    readonly fs_capacity_bytes?: number;
     private _client;
     /**
      * Validate and return the dataplane URL.
@@ -145,4 +155,24 @@ export declare class Sandbox {
      * ```
      */
     delete(): Promise<void>;
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    start(options?: StartSandboxOptions): Promise<void>;
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    stop(): Promise<void>;
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    captureSnapshot(name: string, options?: CaptureSnapshotOptions): Promise<Snapshot>;
 }

package/dist/experimental/sandbox/sandbox.js

@@ -22,6 +22,8 @@ import { reconnectWsStream, runWsStream } from "./ws_execute.js";
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 export class Sandbox {
     /** @internal */
@@ -47,7 +49,7 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Provisioning status ("provisioning", "ready", "failed"). */
+        /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
         Object.defineProperty(this, "status", {
             enumerable: true,
             configurable: true,
@@ -103,6 +105,34 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Snapshot ID used to create this sandbox. */
+        Object.defineProperty(this, "snapshot_id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Number of vCPUs allocated. */
+        Object.defineProperty(this, "vCpus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Memory allocation in bytes. */
+        Object.defineProperty(this, "mem_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Root filesystem capacity in bytes. */
+        Object.defineProperty(this, "fs_capacity_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -120,6 +150,10 @@ export class Sandbox {
         this.ttl_seconds = data.ttl_seconds;
         this.idle_ttl_seconds = data.idle_ttl_seconds;
         this.expires_at = data.expires_at;
+        this.snapshot_id = data.snapshot_id;
+        this.vCpus = data.vcpus;
+        this.mem_bytes = data.mem_bytes;
+        this.fs_capacity_bytes = data.fs_capacity_bytes;
         this._client = client;
     }
     /**
@@ -334,4 +368,34 @@ export class Sandbox {
     async delete() {
         await this._client.deleteSandbox(this.name);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    async start(options = {}) {
+        const refreshed = await this._client.startSandbox(this.name, options);
+        this.status = refreshed.status;
+        this.dataplane_url = refreshed.dataplane_url;
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    async stop() {
+        await this._client.stopSandbox(this.name);
+        this.status = "stopped";
+        this.dataplane_url = undefined;
+    }
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(name, options = {}) {
+        return this._client.captureSnapshot(this.name, name, options);
+    }
 }