@codesandbox/sdk/dist/cjs/Sandboxes.d.ts

The CodeSandbox SDK

import { Sandbox } from "./Sandbox";
import { API } from "./API";
import { Tracer } from "@opentelemetry/api";
import { CreateSandboxOpts, PaginationOpts, SandboxInfo, SandboxListOpts, SandboxListResponse, StartSandboxOpts } from "./types";
/**
 * This class provides methods for creating and managing sandboxes.
 */
export declare class Sandboxes {
    private api;
    private tracer?;
    get defaultTemplateId(): string;
    constructor(api: API, tracer?: Tracer);
    private withSpan;
    /**
     * Resume a sandbox.
     *
     * - Hibernated with snapshot: It wakes up and continues within 2-3 seconds
     * - Hibernated with expired snapshot: It will start from scratch (CLEAN bootup)
     * - Shutdown: It will start from scratch (CLEAN bootup)
     *
     * Note! On CLEAN bootups the setup will run again. When hibernated a new snapshot will be created.
     */
    resume(sandboxId: string): Promise<Sandbox>;
    /**
     * Shuts down a sandbox. Files will be saved, and the sandbox will be stopped.
     */
    shutdown(sandboxId: string): Promise<void>;
    /**
     * Permanently deletes a sandbox. This action is irreversible and will delete all data associated with the sandbox.
     * The sandbox must belong to your team's workspace to be deleted.
     */
    delete(sandboxId: string): Promise<void>;
    /**
     * Forks a sandbox. This will create a new sandbox from the given sandbox.
     * @deprecated This will be removed shortly to avoid having multiple ways of doing the same thing
     */
    fork(sandboxId: string, opts?: StartSandboxOpts): Promise<Sandbox>;
    /**
     * Restart the sandbox. This will shutdown the sandbox, and then start it again. Files in
     * the project directory (`/project/sandbox`) will be preserved.
     *
     * Will resolve once the sandbox is restarted with its setup running.
     */
    restart(sandboxId: string, opts?: StartSandboxOpts): Promise<Sandbox>;
    /**
     * Hibernates a sandbox. Files will be saved, and the sandbox will be put to sleep. Next time
     * you resume the sandbox it will continue from the last state it was in.
     */
    hibernate(sandboxId: string): Promise<void>;
    /**
     * Create a sandbox from a template. By default we will create a sandbox from the default universal template.
     */
    create(opts?: CreateSandboxOpts & StartSandboxOpts): Promise<Sandbox>;
    /**
     * List sandboxes from the current workspace with optional filters.
     *
     * This method supports two modes of operation:
     * 1. Simple limit-based fetching (default):
     *    ```ts
     *    // Get up to 50 sandboxes (default)
     *    const { sandboxes, totalCount } = await client.list();
     *
     *    // Get up to 200 sandboxes
     *    const { sandboxes, totalCount } = await client.list({ limit: 200 });
     *    ```
     *
     * 2. Manual pagination:
     *    ```ts
     *    // Get first page
     *    const { sandboxes, pagination } = await client.list({
     *      pagination: { page: 1, pageSize: 50 }
     *    });
     *    // pagination = { currentPage: 1, nextPage: 2, pageSize: 50 }
     *
     *    // Get next page if available
     *    if (pagination.nextPage) {
     *      const { sandboxes, pagination: nextPagination } = await client.list({
     *        pagination: { page: pagination.nextPage, pageSize: 50 }
     *      });
     *    }
     *    ```
     */
    list(opts?: SandboxListOpts & {
        limit?: number;
        pagination?: PaginationOpts;
    }): Promise<SandboxListResponse>;
    /**
     * List information about currently running VMs.
     *
     * This information is updated roughly every 30 seconds, so this data is not
     * guaranteed to be perfectly up-to-date.
     */
    listRunning(): Promise<{
        concurrentVmCount: number;
        concurrentVmLimit: number;
        vms: {
            id: string | undefined;
            creditBasis: string | undefined;
            lastActiveAt: Date | undefined;
            sessionStartedAt: Date | undefined;
            specs: {
                cpu: number | undefined;
                memory: number | undefined;
                storage: number | undefined;
            } | undefined;
        }[];
    }>;
    /**
     * Get a single sandbox by ID efficiently without listing all sandboxes.
     *
     * This method directly retrieves metadata for a specific sandbox ID,
     * avoiding the performance overhead of the list-and-filter pattern.
     *
     * @param sandboxId The ID of the sandbox to retrieve
     * @returns Promise<SandboxInfo> The sandbox metadata
     * @throws Error if the sandbox is not found or access is denied
     *
     * @example
     * ```ts
     * const sandbox = await client.sandboxes.get("sandbox-id");
     * console.log(sandbox.title, sandbox.tags);
     * ```
     */
    get(sandboxId: string): Promise<SandboxInfo>;
}