langsmith/dist/_openapi_client/resources/sandboxes/boxes.d.ts

Client library to connect to the LangSmith Observability and Evaluation Platform.

import { APIResource } from '../../core/resource.js';
import * as SandboxesAPI from './sandboxes.js';
import { APIPromise } from '../../core/api-promise.js';
import { RequestOptions } from '../../internal/request-options.js';
export declare class Boxes extends APIResource {
    /**
     * Create a new sandbox from a snapshot. Provide at most one of `snapshot_id` or
     * `snapshot_name`; if neither is provided, the server uses the default static
     * blueprint.
     */
    create(body: BoxCreateParams, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxResponse>;
    /**
     * Retrieve a sandbox by name. Stale provisioning sandboxes are auto-failed.
     */
    retrieve(name: string, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxResponse>;
    /**
     * Update a sandbox's display name. The name must be unique within the tenant.
     */
    update(name: string, body: BoxUpdateParams, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxResponse>;
    /**
     * List sandboxes for the authenticated tenant, with optional filtering, sorting,
     * and pagination.
     */
    list(query?: BoxListParams | null | undefined, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxListResponse>;
    /**
     * Delete a sandbox by name or UUID. Tears down the sandbox runtime and removes the
     * DB record.
     */
    delete(name: string, options?: RequestOptions): APIPromise<void>;
    /**
     * Create a snapshot by capturing the current state of a sandbox or promoting an
     * existing checkpoint.
     */
    createSnapshot(name: string, body: BoxCreateSnapshotParams, options?: RequestOptions): APIPromise<SandboxesAPI.SnapshotResponse>;
    /**
     * Create a short-lived JWT for accessing an HTTP service running on a specific
     * port inside a sandbox. Returns a browser_url (sets auth cookie via redirect), a
     * service_url (for use with the X-Langsmith-Sandbox-Service-Token header), the raw
     * token, and its expiry.
     */
    generateServiceURL(name: string, body: BoxGenerateServiceURLParams, options?: RequestOptions): APIPromise<SandboxesAPI.ServiceURLResponse>;
    /**
     * Retrieve the lightweight status of a sandbox for polling.
     */
    getStatus(name: string, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxStatusResponse>;
    /**
     * Start a stopped or failed sandbox. This endpoint is not idempotent.
     */
    start(name: string, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxResponse>;
    /**
     * Stop a ready sandbox. This endpoint is not idempotent; the filesystem is
     * preserved for later restart.
     */
    stop(name: string, options?: RequestOptions): APIPromise<void>;
}
export interface BoxCreateParams {
    /**
     * CPUMillicores optionally requests CPU at millicore granularity (e.g. 500 = 0.5
     * vCPU); takes precedence over VCPUs. Fractional (sub-vCPU) values are not
     * available for every sandbox.
     */
    cpu_millicores?: number;
    delete_after_stop_seconds?: number;
    env_vars?: {
        [key: string]: string;
    };
    fs_capacity_bytes?: number;
    idle_ttl_seconds?: number;
    mem_bytes?: number;
    mount_config?: BoxCreateParams.MountConfig;
    name?: string;
    proxy_config?: BoxCreateParams.ProxyConfig;
    /**
     * RestoreMemory selects how the sandbox handles a snapshot's captured memory:
     *
     * nil → if-present: resume from memory when the snapshot has it, else cold-boot
     * (default). true → always: resume from memory; rejected if the snapshot has none.
     * false → never: always cold-boot.
     *
     * Applies to this request only.
     */
    restore_memory?: boolean;
    snapshot_id?: string;
    snapshot_name?: string;
    tag_value_ids?: Array<string>;
    vcpus?: number;
}
export declare namespace BoxCreateParams {
    interface MountConfig {
        auth?: MountConfig.Auth;
        mounts?: Array<MountConfig.SandboxapiS3BucketMountSpec | MountConfig.SandboxapiGcsBucketMountSpec | MountConfig.SandboxapiGitRepoMountSpec>;
    }
    namespace MountConfig {
        interface Auth {
            aws?: Auth.Aws;
            gcp?: Auth.Gcp;
        }
        namespace Auth {
            interface Aws {
                access_key_id: Aws.AccessKeyID;
                secret_access_key: Aws.SecretAccessKey;
            }
            namespace Aws {
                interface AccessKeyID {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
                interface SecretAccessKey {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
            interface Gcp {
                service_account_json: Gcp.ServiceAccountJson;
            }
            namespace Gcp {
                interface ServiceAccountJson {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
        }
        interface SandboxapiS3BucketMountSpec {
            id: string;
            mount_path: string;
            s3: SandboxapiS3BucketMountSpec.S3;
            type: 's3' | 'gcs' | 'git';
            cache?: SandboxapiS3BucketMountSpec.Cache;
            gcs?: SandboxapiS3BucketMountSpec.Gcs;
            git?: SandboxapiS3BucketMountSpec.Git;
            read_only?: boolean;
        }
        namespace SandboxapiS3BucketMountSpec {
            interface S3 {
                bucket: string;
                region: string;
                endpoint_url?: string;
                path_style?: boolean;
                prefix?: string;
            }
            interface Cache {
                max_size_bytes?: number;
                writeback_seconds?: number;
            }
            interface Gcs {
                bucket: string;
                prefix?: string;
            }
            interface Git {
                remote_url: string;
                ref?: Git.Ref;
                refresh_interval_seconds?: number;
            }
            namespace Git {
                interface Ref {
                    name: string;
                    type: 'branch' | 'tag';
                }
            }
        }
        interface SandboxapiGcsBucketMountSpec {
            id: string;
            gcs: SandboxapiGcsBucketMountSpec.Gcs;
            mount_path: string;
            type: 's3' | 'gcs' | 'git';
            cache?: SandboxapiGcsBucketMountSpec.Cache;
            git?: SandboxapiGcsBucketMountSpec.Git;
            read_only?: boolean;
            s3?: SandboxapiGcsBucketMountSpec.S3;
        }
        namespace SandboxapiGcsBucketMountSpec {
            interface Gcs {
                bucket: string;
                prefix?: string;
            }
            interface Cache {
                max_size_bytes?: number;
                writeback_seconds?: number;
            }
            interface Git {
                remote_url: string;
                ref?: Git.Ref;
                refresh_interval_seconds?: number;
            }
            namespace Git {
                interface Ref {
                    name: string;
                    type: 'branch' | 'tag';
                }
            }
            interface S3 {
                bucket: string;
                region: string;
                endpoint_url?: string;
                path_style?: boolean;
                prefix?: string;
            }
        }
        interface SandboxapiGitRepoMountSpec {
            id: string;
            git: SandboxapiGitRepoMountSpec.Git;
            mount_path: string;
            type: 's3' | 'gcs' | 'git';
            cache?: SandboxapiGitRepoMountSpec.Cache;
            gcs?: SandboxapiGitRepoMountSpec.Gcs;
            read_only?: boolean;
            s3?: SandboxapiGitRepoMountSpec.S3;
        }
        namespace SandboxapiGitRepoMountSpec {
            interface Git {
                remote_url: string;
                ref?: Git.Ref;
                refresh_interval_seconds?: number;
            }
            namespace Git {
                interface Ref {
                    name: string;
                    type: 'branch' | 'tag';
                }
            }
            interface Cache {
                max_size_bytes?: number;
                writeback_seconds?: number;
            }
            interface Gcs {
                bucket: string;
                prefix?: string;
            }
            interface S3 {
                bucket: string;
                region: string;
                endpoint_url?: string;
                path_style?: boolean;
                prefix?: string;
            }
        }
    }
    interface ProxyConfig {
        access_control?: ProxyConfig.AccessControl;
        callbacks?: Array<ProxyConfig.Callback>;
        no_proxy?: Array<string>;
        rules?: Array<ProxyConfig.Rule>;
    }
    namespace ProxyConfig {
        interface AccessControl {
            allow_list?: Array<string>;
            deny_list?: Array<string>;
        }
        interface Callback {
            match_hosts: Array<string>;
            ttl_seconds: number;
            url: string;
            full_request?: boolean;
            request_headers?: Array<Callback.RequestHeader>;
        }
        namespace Callback {
            interface RequestHeader {
                name: string;
                type: 'plaintext' | 'opaque' | 'workspace_secret';
                is_set?: boolean;
                value?: string;
            }
        }
        interface Rule {
            name: string;
            aws?: Rule.Aws;
            enabled?: boolean;
            gcp?: Rule.Gcp;
            headers?: Array<Rule.Header>;
            /**
             * MatchHosts is only accepted for header injection rules. Provider auth rules use
             * built-in host matching.
             */
            match_hosts?: Array<string>;
            match_paths?: Array<string>;
            type?: string;
        }
        namespace Rule {
            interface Aws {
                access_key_id: Aws.AccessKeyID;
                secret_access_key: Aws.SecretAccessKey;
            }
            namespace Aws {
                interface AccessKeyID {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
                interface SecretAccessKey {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
            interface Gcp {
                scopes: Array<string>;
                service_account_json: Gcp.ServiceAccountJson;
            }
            namespace Gcp {
                interface ServiceAccountJson {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
            interface Header {
                name: string;
                type: 'plaintext' | 'opaque' | 'workspace_secret';
                is_set?: boolean;
                value?: string;
            }
        }
    }
}
export interface BoxUpdateParams {
    cpu_millicores?: number;
    delete_after_stop_seconds?: number;
    fs_capacity_bytes?: number;
    idle_ttl_seconds?: number;
    mem_bytes?: number;
    name?: string;
    proxy_config?: BoxUpdateParams.ProxyConfig;
    tag_value_ids?: Array<string>;
    vcpus?: number;
}
export declare namespace BoxUpdateParams {
    interface ProxyConfig {
        access_control?: ProxyConfig.AccessControl;
        callbacks?: Array<ProxyConfig.Callback>;
        no_proxy?: Array<string>;
        rules?: Array<ProxyConfig.Rule>;
    }
    namespace ProxyConfig {
        interface AccessControl {
            allow_list?: Array<string>;
            deny_list?: Array<string>;
        }
        interface Callback {
            match_hosts: Array<string>;
            ttl_seconds: number;
            url: string;
            full_request?: boolean;
            request_headers?: Array<Callback.RequestHeader>;
        }
        namespace Callback {
            interface RequestHeader {
                name: string;
                type: 'plaintext' | 'opaque' | 'workspace_secret';
                is_set?: boolean;
                value?: string;
            }
        }
        interface Rule {
            name: string;
            aws?: Rule.Aws;
            enabled?: boolean;
            gcp?: Rule.Gcp;
            headers?: Array<Rule.Header>;
            /**
             * MatchHosts is only accepted for header injection rules. Provider auth rules use
             * built-in host matching.
             */
            match_hosts?: Array<string>;
            match_paths?: Array<string>;
            type?: string;
        }
        namespace Rule {
            interface Aws {
                access_key_id: Aws.AccessKeyID;
                secret_access_key: Aws.SecretAccessKey;
            }
            namespace Aws {
                interface AccessKeyID {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
                interface SecretAccessKey {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
            interface Gcp {
                scopes: Array<string>;
                service_account_json: Gcp.ServiceAccountJson;
            }
            namespace Gcp {
                interface ServiceAccountJson {
                    type: 'plaintext' | 'opaque' | 'workspace_secret';
                    is_set?: boolean;
                    value?: string;
                }
            }
            interface Header {
                name: string;
                type: 'plaintext' | 'opaque' | 'workspace_secret';
                is_set?: boolean;
                value?: string;
            }
        }
    }
}
export interface BoxListParams {
    /**
     * Filter by creator identity. Only 'me' is supported.
     */
    created_by?: string;
    /**
     * Maximum number of results
     */
    limit?: number;
    /**
     * Filter by name substring
     */
    name_contains?: string;
    /**
     * Pagination offset
     */
    offset?: number;
    /**
     * Sort column (name, status, created_at)
     */
    sort_by?: string;
    /**
     * Sort direction (asc, desc)
     */
    sort_direction?: string;
    /**
     * Filter by status (provisioning, ready, failed, stopped, deleting)
     */
    status?: string;
}
export interface BoxCreateSnapshotParams {
    name: string;
    /**
     * if omitted, creates a fresh checkpoint from the running VM
     */
    checkpoint?: string;
    /**
     * sandbox-local Docker image to export
     */
    docker_image?: string;
    /**
     * required for Docker image export unless the sandbox has a capacity
     */
    fs_capacity_bytes?: number;
    /**
     * IncludeMemory, when true, captures a full VM memory snapshot alongside the
     * filesystem clone. Only honored when the sandbox is running AND Checkpoint is
     * omitted (i.e. a fresh in-VM checkpoint is requested). Defaults to false to keep
     * snapshots small unless memory restore is explicitly desired.
     */
    include_memory?: boolean;
}
export interface BoxGenerateServiceURLParams {
    expires_in_seconds?: number;
    port?: number;
}
export declare namespace Boxes {
    export { type BoxCreateParams as BoxCreateParams, type BoxUpdateParams as BoxUpdateParams, type BoxListParams as BoxListParams, type BoxCreateSnapshotParams as BoxCreateSnapshotParams, type BoxGenerateServiceURLParams as BoxGenerateServiceURLParams, };
}