import { APIResource } from '../../core/resource.js'; import * as SandboxesAPI from './sandboxes.js'; import { SandboxResponsesItemsCursorGetPagination } from './sandboxes.js'; import { APIPromise } from '../../core/api-promise.js'; import { type ItemsCursorGetPaginationParams, PagePromise } from '../../core/pagination.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 snapshot. * `snapshot_name` accepts a Docker-style `name` or `name:tag` reference (a bare * name resolves to `name:latest`). */ create(body: BoxCreateParams, options?: RequestOptions): APIPromise; /** * Retrieve a sandbox by name. Stale provisioning sandboxes are auto-failed. */ retrieve(name: string, options?: RequestOptions): APIPromise; /** * Update a sandbox's display name, retention, resources, tags, or proxy * configuration. The name must be unique within the tenant. Proxy configuration * sent to a sandbox that is not running is stored and applied when it next starts. */ update(name: string, body: BoxUpdateParams, options?: RequestOptions): APIPromise; /** * List sandboxes for the authenticated tenant, with optional filtering, sorting, * and pagination. Page with page_size and cursor: replay the response's * next_cursor until it comes back null, which is the only signal that no pages * remain. Cursors are opaque and only valid on this endpoint; do not parse or * construct one. */ list(query?: BoxListParams | null | undefined, options?: RequestOptions): PagePromise; /** * Delete a sandbox by name or UUID. Tears down the sandbox runtime and removes the * DB record. */ delete(name: string, options?: RequestOptions): APIPromise; /** * Create a snapshot by capturing the current state of a sandbox or promoting an * existing checkpoint. */ createSnapshot(name: string, body: BoxCreateSnapshotParams, options?: RequestOptions): APIPromise; /** * Generate a tokenized link that downloads a single file from a sandbox with no * further authentication. This mints a token rather than creating an addressable * resource, so it returns 200 with no Location header. The token pins the sandbox, * the file path, and the response content type and disposition, so a link cannot * be repointed at another file. Links never expire unless expires_in_seconds is * set. The link is served from the sandbox service domain, not the API host. */ generateDownloadURL(name: string, body: BoxGenerateDownloadURLParams, options?: RequestOptions): APIPromise; /** * 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; /** * Retrieve the lightweight status of a sandbox for polling. */ getStatus(name: string, options?: RequestOptions): APIPromise; /** * Start a stopped or failed sandbox. This endpoint is not idempotent. */ start(name: string, options?: RequestOptions): APIPromise; /** * Stop a ready sandbox. This endpoint is not idempotent; the filesystem is * preserved for later restart. */ stop(name: string, options?: RequestOptions): APIPromise; } 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; /** * Labels are free-form key/value metadata persisted with the sandbox and returned * on reads. Labels from the source snapshot are inherited unless overridden here. */ labels?: { [key: string]: string; }; /** * Memory for the sandbox, in bytes. Memory is tied to CPU at 4 GiB per vCPU: omit * it and it follows that ratio; set it and it must stay within 50% of the ratio * for the requested CPU, so a 1 vCPU sandbox accepts 2-6 GiB. Setting memory * without CPU derives the CPU from the same ratio. Maximum 64 GiB. */ mem_bytes?: number; mount_config?: BoxCreateParams.MountConfig; name?: string; /** * PreserveMemoryOnStop, when true, suspends the sandbox's memory on a voluntary * stop (idle timeout or explicit stop) so the next start resumes from where it * left off. Default false discards memory and keeps only the filesystem, so the * next start is a cold boot. Restarts triggered by infrastructure maintenance * always preserve memory regardless of this setting. */ preserve_memory_on_stop?: boolean; 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 is a Docker-style name or name:tag reference to boot from. A bare name * resolves to name:latest. */ snapshot?: string; snapshot_id?: string; /** * SnapshotName is a synonym for Snapshot, accepted for compatibility with clients * that predate it. Set one or the other. */ snapshot_name?: string; tag_value_ids?: Array; vcpus?: number; } export declare namespace BoxCreateParams { interface MountConfig { auth?: MountConfig.Auth; mounts?: Array; } 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' | 'contexthub'; cache?: SandboxapiS3BucketMountSpec.Cache; contexthub?: SandboxapiS3BucketMountSpec.Contexthub; 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 Contexthub { /** * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent", * where "-" is the current workspace). The repo's latest commit tree is mirrored * into the mount path. */ repo: string; /** * InitialPullOnly syncs the repo once at startup instead of polling for updates * for the sandbox's lifetime. */ initial_pull_only?: boolean; } 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' | 'contexthub'; cache?: SandboxapiGcsBucketMountSpec.Cache; contexthub?: SandboxapiGcsBucketMountSpec.Contexthub; 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 Contexthub { /** * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent", * where "-" is the current workspace). The repo's latest commit tree is mirrored * into the mount path. */ repo: string; /** * InitialPullOnly syncs the repo once at startup instead of polling for updates * for the sandbox's lifetime. */ initial_pull_only?: boolean; } 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' | 'contexthub'; cache?: SandboxapiGitRepoMountSpec.Cache; contexthub?: SandboxapiGitRepoMountSpec.Contexthub; 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 Contexthub { /** * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent", * where "-" is the current workspace). The repo's latest commit tree is mirrored * into the mount path. */ repo: string; /** * InitialPullOnly syncs the repo once at startup instead of polling for updates * for the sandbox's lifetime. */ initial_pull_only?: boolean; } interface Gcs { bucket: string; prefix?: string; } interface S3 { bucket: string; region: string; endpoint_url?: string; path_style?: boolean; prefix?: string; } } interface SandboxapiContextHubRepoMountSpec { id: string; contexthub: SandboxapiContextHubRepoMountSpec.Contexthub; mount_path: string; type: 's3' | 'gcs' | 'git' | 'contexthub'; cache?: SandboxapiContextHubRepoMountSpec.Cache; gcs?: SandboxapiContextHubRepoMountSpec.Gcs; git?: SandboxapiContextHubRepoMountSpec.Git; read_only?: boolean; s3?: SandboxapiContextHubRepoMountSpec.S3; } namespace SandboxapiContextHubRepoMountSpec { interface Contexthub { /** * Repo is the Context Hub repository to sync, as "owner/repo" (e.g. "-/my-agent", * where "-" is the current workspace). The repo's latest commit tree is mirrored * into the mount path. */ repo: string; /** * InitialPullOnly syncs the repo once at startup instead of polling for updates * for the sandbox's lifetime. */ initial_pull_only?: boolean; } 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 S3 { bucket: string; region: string; endpoint_url?: string; path_style?: boolean; prefix?: string; } } } interface ProxyConfig { access_control?: ProxyConfig.AccessControl; callbacks?: Array; no_proxy?: Array; rules?: Array; } namespace ProxyConfig { interface AccessControl { allow_list?: Array; deny_list?: Array; } interface Callback { match_hosts: Array; ttl_seconds: number; url: string; full_request?: boolean; request_headers?: Array; } 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; /** * EnvVars are plaintext env vars set for every command in the sandbox while this * rule is enabled. Use them for tools that refuse to run unless a credential env * var is present (e.g. gh needs GH_TOKEN) even though this rule injects the real * credential on the wire — set a dummy value here so the command starts. Explicit * per-sandbox env_vars win over these, and provider-managed (AWS/GCP) vars win * over both. */ env_vars?: { [key: string]: string; }; gcp?: Rule.Gcp; headers?: Array; /** * MatchHosts is only accepted for header injection rules. Provider auth rules use * built-in host matching. */ match_hosts?: Array; match_paths?: Array; 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; 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; /** * New memory for the sandbox, in bytes. The 4 GiB per vCPU ratio applies when the * sandbox is created; a resize enforces only the maximum of 64 GiB. */ mem_bytes?: number; name?: string; proxy_config?: BoxUpdateParams.ProxyConfig; tag_value_ids?: Array; vcpus?: number; } export declare namespace BoxUpdateParams { interface ProxyConfig { access_control?: ProxyConfig.AccessControl; callbacks?: Array; no_proxy?: Array; rules?: Array; } namespace ProxyConfig { interface AccessControl { allow_list?: Array; deny_list?: Array; } interface Callback { match_hosts: Array; ttl_seconds: number; url: string; full_request?: boolean; request_headers?: Array; } 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; /** * EnvVars are plaintext env vars set for every command in the sandbox while this * rule is enabled. Use them for tools that refuse to run unless a credential env * var is present (e.g. gh needs GH_TOKEN) even though this rule injects the real * credential on the wire — set a dummy value here so the command starts. Explicit * per-sandbox env_vars win over these, and provider-managed (AWS/GCP) vars win * over both. */ env_vars?: { [key: string]: string; }; gcp?: Rule.Gcp; headers?: Array; /** * MatchHosts is only accepted for header injection rules. Provider auth rules use * built-in host matching. */ match_hosts?: Array; match_paths?: Array; 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; 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 extends ItemsCursorGetPaginationParams { /** * Filter by creator identity. Only 'me' is supported. */ created_by?: string; /** * Filter by label. Repeatable; all must match. Use 'key' to match on key presence * or 'key=value' for equality. */ label?: Array; /** * Deprecated: use page_size. Maximum number of results */ limit?: number; /** * Filter by name substring */ name_contains?: string; /** * Deprecated: use cursor. Pagination offset */ offset?: number; /** * Sort column (name, status, created_at, stopped_at, idle_ttl_seconds, * delete_after_stop_seconds) */ sort_by?: string; /** * Deprecated: use sort_order. Sort direction (asc, desc) */ sort_direction?: string; /** * Sort direction (asc, desc) */ sort_order?: 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; /** * Labels seed the captured snapshot's labels. */ labels?: { [key: string]: string; }; /** * mutable Docker-style tag; defaults to "latest" */ tag?: string; } export interface BoxGenerateDownloadURLParams { path: string; content_disposition?: string; content_type?: string; /** * ExpiresInSeconds is optional; a link with no expiry never expires. */ expires_in_seconds?: number; } 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 BoxGenerateDownloadURLParams as BoxGenerateDownloadURLParams, type BoxGenerateServiceURLParams as BoxGenerateServiceURLParams, }; } export { type SandboxResponsesItemsCursorGetPagination };