import { Pod, PodInstance } from "./pod"; import { CreateStubConfig } from "./stub"; import type { PodInstanceData, ExecOptions } from "../../types/pod"; /** Error thrown when connecting to a sandbox fails. */ export declare class SandboxConnectionError extends Error { } /** Error thrown for sandbox filesystem operations. */ export declare class SandboxFileSystemError extends Error { } /** Error thrown for sandbox process operations. */ export declare class SandboxProcessError extends Error { } export interface SandboxCreateOptions { entrypoint?: string[]; waitForReady?: boolean; } /** * A sandboxed container for running code or arbitrary processes. * You can use this to create isolated environments where you can execute code, * manage files, and run processes. * * Constructor parameters: * - config (CreateStubConfig): Base stub configuration for the sandbox. * - syncLocalDir (boolean): Whether to sync the local working directory on creation. * Default is false. * * Config fields (selected): * - name (string): The sandbox app name (required). * - cpu (number | string): The number of CPU cores allocated to the container. Default is 1. * - memory (number | string): The amount of memory allocated to the container. It should be specified in * MiB, or as a string with units (e.g. "1Gi"). Default is 128 MiB. * - gpu (GpuType | string | Array): The GPU type(s) to use. Default is GpuType.NoGPU. * - gpuCount (number): The number of GPUs to allocate. Default is 0 (auto-promotes to 1 if gpu is set). * - image (Image): The container image used for the sandbox. * - keepWarmSeconds (number): The number of seconds to keep the sandbox around. Default is 60s. Use -1 * for sandboxes that never timeout. * - volumes (Volume[]): The volumes and/or cloud buckets to mount into the sandbox container. * - secrets (SecretVar[]): Secrets to pass to the sandbox, e.g. [{ name: "API_KEY" }]. * - blockNetwork (boolean): Whether to block all outbound network access. Cannot be combined with * `allowList`. * - allowList (string[]): CIDR ranges that are allowed for outbound network access. When specified, * all other outbound traffic is blocked. * - dockerEnabled (boolean): Start the managed Docker daemon. Defaults to false; pair with * `Image.withDocker()` or an image that already contains Docker. * - authorized (boolean): Ignored for sandboxes (forced to false). */ export declare class Sandbox extends Pod { syncLocalDir: boolean; private runtimePreparation?; constructor(config: CreateStubConfig, syncLocalDir?: boolean); /** * Connect to an existing sandbox instance by ID. * * Parameters: * - id (string): The container ID of the existing sandbox instance. * * Returns: SandboxInstance - A connected sandbox instance. * * Throws: SandboxConnectionError if the connection fails. */ static connect(id: string): Promise; /** Terminate a sandbox by ID without connecting to it first. */ static terminate(id: string): Promise; /** * Create a sandbox instance from a filesystem snapshot. * * Parameters: * - snapshotId (string): The ID of the snapshot to create the sandbox from. * * Returns: SandboxInstance - A new sandbox instance ready for use. * * Throws: SandboxConnectionError if the sandbox creation fails. */ static createFromSnapshot(snapshotId: string): Promise; /** * Create a new sandbox instance. * * This method creates a new containerized sandbox environment with the * specified configuration. * * Returns: SandboxInstance - A new sandbox instance ready for use. * * Throws: SandboxConnectionError if the sandbox creation fails. */ create(entrypointOrOptions?: string[] | SandboxCreateOptions): Promise; private createContainer; } /** * A sandbox instance that provides access to the sandbox internals. * * This class represents an active sandboxed container and provides methods for * process management, file system operations, preview URLs, and lifecycle * management. * * Attributes: * - containerId (string): The unique ID of the created sandbox container. * - stubId (string): The stub ID used for sandbox operations. * - fs (SandboxFileSystem): File system interface for the sandbox. * - processes (Record): Map of running processes by PID. * - terminated (boolean): Whether the sandbox has been terminated. * * Process Management Methods: * - runCode(code, blocking?, cwd?, env?): Execute Python code in the sandbox. * - exec(command, opts?): Run argv safely or shell text for string input. * - execShell(command, opts?): Run shell text exactly as provided. * - listProcesses(): Get running processes from the server. */ export declare class SandboxInstance extends PodInstance { stubId: string; fs: SandboxFileSystem; processes: Record; terminated: boolean; constructor(data: { stubId: string; } & PodInstanceData, pod: Pod); /** * Create a snapshot of the sandbox memory and filesystem. * * @returns string - The snapshot ID. */ snapshot(): Promise; /** * Create an image from the sandbox filesystem * @returns string - The image ID. */ createImageFromFilesystem(): Promise; /** Get the ID of the sandbox. */ get sandboxId(): string; /** * Update the keep warm setting of the sandbox. * * Parameters: ttl (number): The number of seconds to keep the sandbox alive. Use -1 for never timeout. */ updateTtl(ttl: number): Promise; /** * Dynamically expose a port to the internet. Returns the public URL. */ exposePort(port: number): Promise; /** * Dynamically update outbound network permissions for the sandbox. * * Parameters: * - blockNetwork (boolean): If true, block all outbound network access. Defaults to false. * - allowList (string[]): Optional list of allowed outbound domains/IPs. Cannot be used with blockNetwork=true. * * Throws: SandboxConnectionError if the update fails. */ updateNetworkPermissions(blockNetwork?: boolean, allowList?: string[]): Promise; /** * List all exposed URLs in the sandbox, keyed by port. */ listUrls(): Promise>; /** * Terminate the sandbox instance. */ terminate(): Promise; /** * Run Python code in the sandbox. * * Parameters: * - code (string): The Python code to execute. * - blocking (boolean): Wait for completion and return response; otherwise return a SandboxProcess. * - cwd (string | undefined): Working directory. * - env (Record | undefined): Environment variables. */ runCode(code: string, blocking?: boolean, cwd?: string, env?: Record): Promise; /** Run an arbitrary command in the sandbox. */ exec(command: string | string[], opts?: ExecOptions): Promise; /** Run shell text in the sandbox exactly as provided. */ execShell(command: string, opts?: ExecOptions): Promise; private _exec; /** List all processes running in the sandbox. */ listProcesses(): Promise; /** Get a process handle by PID from the local cache. Call listProcesses() first to refresh from the server. */ getProcess(pid: number): SandboxProcess; } /** * Response object containing the results of a completed process execution. * * This class encapsulates the output and status information from a process * that has finished running in the sandbox. * * Attributes: * - pid (number): The process ID of the executed command. * - exitCode (number): The exit code of the process (0 typically indicates success). * - stdout (string): The full standard output captured for the process. * - stderr (string): The full standard error output captured for the process. * - result (string): Combined stdout and stderr output as a string. */ export interface SandboxProcessResponse { pid: number; exitCode: number; stdout: string; stderr: string; result: string; } /** * A stream-like interface for reading process output in real-time. * * Provides an iterator interface and bulk reading capabilities. */ export declare class SandboxProcessStream { process: SandboxProcess; private fetch_fn; private _buffer; private _closed; private _last_output; constructor(process: SandboxProcess, fetchFn: () => Promise | string, initialOutput?: string); [Symbol.asyncIterator](): AsyncIterableIterator; private _fetch_next_chunk; /** * Fetch and return all available output at this moment. */ read(): Promise; } /** * Represents a running process within a sandbox. * * Control and monitoring capabilities for processes running in the sandbox. */ export declare class SandboxProcess { sandbox_instance: SandboxInstance; pid: number; exitCode: number; cwd: string; command: string; env: string[]; running: boolean; private _status; private _inlineDone; private _inlineStdout; private _inlineStderr; constructor(sandboxInstance: SandboxInstance, pid: number, info?: { cwd?: string; command?: string; env?: string[]; exitCode?: number; running?: boolean; done?: boolean; stdout?: string; stderr?: string; }); /** Wait for the process to complete and return the exit code. */ wait(): Promise; /** Return the latest exit code and status string. */ poll(): Promise<[number, string]>; /** Kill the process. */ kill(): Promise; /** Get the status of the process: [exitCode, status]. */ status(opts?: { timeoutMs?: number; signal?: AbortSignal; }): Promise<[number, string]>; /** Get a handle to a stream of the process's stdout. */ get stdout(): SandboxProcessStream; /** Get a handle to a stream of the process's stderr. */ get stderr(): SandboxProcessStream; /** Returns a combined stream of both stdout and stderr. */ get logs(): { _stdout: SandboxProcessStream; _stderr: SandboxProcessStream; _queue: string[]; _stdoutBuffer: string; _stderrBuffer: string; _stdoutExhausted: boolean; _stderrExhausted: boolean; _process_stream(streamName: "stdout" | "stderr"): Promise; _fill_queue(): Promise; read(): Promise; [Symbol.asyncIterator](): AsyncIterableIterator; }; } /** Metadata of a file in the sandbox. */ export declare class SandboxFileInfo { name: string; isDir: boolean; size: number; mode: number; modTime: number; permissions: number; owner: string; group: string; constructor(init: { name: string; isDir: boolean; size: number; mode: number; modTime: number; permissions: number; owner: string; group: string; }); toString(): string; } /** A position in a file. */ export declare class SandboxFilePosition { line: number; column: number; constructor(line: number, column: number); } /** A range in a file. */ export declare class SandboxFileSearchRange { start: SandboxFilePosition; end: SandboxFilePosition; constructor(start: SandboxFilePosition, end: SandboxFilePosition); } /** A match in a file. */ export declare class SandboxFileSearchMatch { range: SandboxFileSearchRange; content: string; constructor(range: SandboxFileSearchRange, content: string); } /** A search result in a file. */ export declare class SandboxFileSearchResult { path: string; matches: SandboxFileSearchMatch[]; constructor(path: string, matches: SandboxFileSearchMatch[]); } /** * File system interface for managing files within a sandbox. * * Upload, download, stat, list, and manage files and directories. */ export declare class SandboxFileSystem { private sandbox_instance; constructor(sandboxInstance: SandboxInstance); /** Upload a local file to the sandbox. */ upload(localPath: string, sandboxPath: string): Promise; /** Upload a local file to the sandbox. */ uploadFile(localPath: string, sandboxPath: string): Promise; /** Write bytes to a file in the sandbox. */ writeBytes(sandboxPath: string, content: Buffer | Uint8Array | string, mode?: number): Promise; /** Write text to a file in the sandbox. */ writeText(sandboxPath: string, content: string, mode?: number): Promise; /** Download a file from the sandbox and return its bytes. */ download(sandboxPath: string): Promise; /** Download a file from the sandbox to a local path. */ downloadFile(sandboxPath: string, localPath: string): Promise; /** Read a file from the sandbox as bytes. */ readBytes(sandboxPath: string): Promise; /** Read a file from the sandbox as UTF-8 text. */ readText(sandboxPath: string): Promise; /** Get the metadata of a file in the sandbox. */ stat(sandboxPath: string): Promise; /** Get the metadata of a file in the sandbox. */ statFile(sandboxPath: string): Promise; /** List the files in a directory in the sandbox. */ list(sandboxPath: string): Promise; /** List the files in a directory in the sandbox. */ listFiles(sandboxPath: string): Promise; /** Create a directory in the sandbox. */ mkdir(sandboxPath: string): Promise; /** Create a directory in the sandbox. */ createDirectory(sandboxPath: string): Promise; /** Delete a directory in the sandbox. */ removeDir(sandboxPath: string): Promise; /** Delete a directory in the sandbox. */ deleteDirectory(sandboxPath: string): Promise; /** Delete a file in the sandbox. */ removeFile(sandboxPath: string): Promise; /** Delete a file in the sandbox. */ deleteFile(sandboxPath: string): Promise; /** Delete a file or directory in the sandbox. */ remove(sandboxPath: string, opts?: { dir?: boolean; }): Promise; /** Replace a string in all files in a directory. */ replace(sandboxPath: string, oldString: string, newString: string): Promise; /** Replace a string in all files in a directory. */ replaceInFiles(sandboxPath: string, oldString: string, newString: string): Promise; /** Find files matching a pattern in the sandbox. */ find(sandboxPath: string, pattern: string): Promise; /** Find files matching a pattern in the sandbox. */ findInFiles(sandboxPath: string, pattern: string): Promise; }