computesdk 1.18.2 → 1.19.0

package/dist/index.d.ts

@@ -113,8 +113,36 @@ interface CreateSandboxOptions$1 {
     envs?: Record<string, string>;
     name?: string;
     namespace?: string;
+    directory?: string;
+    overlays?: SandboxOverlayConfig[];
+    servers?: SandboxServerConfig[];
     [key: string]: any;
 }
+interface SandboxOverlayConfig {
+    source: string;
+    target: string;
+    ignore?: string[];
+    strategy?: 'copy' | 'smart';
+}
+type SandboxRestartPolicy = 'never' | 'on-failure' | 'always';
+interface SandboxServerConfig {
+    slug: string;
+    start: string;
+    install?: string;
+    path?: string;
+    port?: number;
+    strict_port?: boolean;
+    autostart?: boolean;
+    env_file?: string;
+    environment?: Record<string, string>;
+    restart_policy?: SandboxRestartPolicy;
+    max_restarts?: number;
+    restart_delay_ms?: number;
+    stop_timeout_ms?: number;
+    depends_on?: string[];
+    overlay?: SandboxOverlayConfig;
+    overlays?: SandboxOverlayConfig[];
+}
 /**
  * Universal Sandbox Interface
  *
@@ -1099,6 +1127,212 @@ declare class Terminal {
     destroy(id: string): Promise<void>;
 }
 
+/**
+ * Overlay - Resource namespace for filesystem overlay operations
+ *
+ * Overlays enable instant sandbox setup from template directories by copying
+ * files directly for isolation, with heavy directories copied in the background.
+ */
+/**
+ * Options for waiting for overlay copy completion
+ */
+interface WaitForCompletionOptions {
+    /** Maximum number of retry attempts (default: 60) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 500) */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds (default: 5000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff (default: 1.5) */
+    backoffFactor?: number;
+}
+/**
+ * Strategy for creating an overlay
+ * - 'copy': Full copy of all files (standard behavior)
+ * - 'smart': Use symlinks for immutable packages (e.g. node_modules) for instant creation
+ */
+type OverlayStrategy = 'copy' | 'smart';
+/**
+ * Options for creating an overlay
+ */
+interface CreateOverlayOptions {
+    /** Absolute path to source directory (template) */
+    source: string;
+    /** Relative path in sandbox where overlay will be mounted */
+    target: string;
+    /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
+    ignore?: string[];
+    /** Strategy to use (default: 'smart') */
+    strategy?: OverlayStrategy;
+    /** If true, wait for background copy to complete before returning (default: false) */
+    waitForCompletion?: boolean | WaitForCompletionOptions;
+}
+/**
+ * Copy status for overlay background operations
+ */
+type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+/**
+ * Statistics about an overlay
+ */
+interface OverlayStats {
+    /** Number of copied files */
+    copiedFiles: number;
+    /** Number of copied directories (heavy dirs copied in background) */
+    copiedDirs: number;
+    /** Paths that were skipped (e.g., .git, ignored patterns) */
+    skipped: string[];
+}
+/**
+ * Overlay information (client-side normalized type)
+ */
+interface OverlayInfo {
+    /** Unique overlay identifier */
+    id: string;
+    /** Absolute path to source directory */
+    source: string;
+    /** Relative path in sandbox */
+    target: string;
+    /** Strategy used for the overlay */
+    strategy: OverlayStrategy;
+    /** When the overlay was created */
+    createdAt: string;
+    /** Statistics about the overlay */
+    stats: OverlayStats;
+    /** Copy status for background operations */
+    copyStatus: OverlayCopyStatus;
+    /** Error message if copy failed */
+    copyError?: string;
+}
+/**
+ * API response for overlay operations (snake_case from server)
+ */
+interface OverlayResponse {
+    id: string;
+    source: string;
+    target: string;
+    strategy?: string;
+    created_at: string;
+    stats: {
+        copied_files: number;
+        copied_dirs: number;
+        skipped: string[];
+    };
+    copy_status: string;
+    copy_error?: string;
+}
+/**
+ * API response for listing overlays
+ */
+interface OverlayListResponse {
+    overlays: OverlayResponse[];
+}
+/**
+ * Overlay resource namespace
+ *
+ * @example
+ * ```typescript
+ * // Create an overlay from a template directory
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ * });
+ * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+ *
+ * // Create an overlay and wait for background copy to complete
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ *   waitForCompletion: true, // blocks until copy is complete
+ * });
+ *
+ * // Wait for an existing overlay's copy to complete
+ * const overlay = await sandbox.filesystem.overlay.waitForCompletion('overlay-id');
+ *
+ * // List all overlays
+ * const overlays = await sandbox.filesystem.overlay.list();
+ *
+ * // Get a specific overlay (useful for polling copy status)
+ * const overlay = await sandbox.filesystem.overlay.retrieve('overlay-id');
+ * if (overlay.copyStatus === 'complete') {
+ *   console.log('Background copy finished!');
+ * }
+ *
+ * // Delete an overlay
+ * await sandbox.filesystem.overlay.destroy('overlay-id');
+ * ```
+ */
+declare class Overlay {
+    private createHandler;
+    private listHandler;
+    private retrieveHandler;
+    private destroyHandler;
+    constructor(handlers: {
+        create: (options: CreateOverlayOptions) => Promise<OverlayResponse>;
+        list: () => Promise<OverlayListResponse>;
+        retrieve: (id: string) => Promise<OverlayResponse>;
+        destroy: (id: string) => Promise<void>;
+    });
+    /**
+     * Create a new overlay from a template directory
+     *
+     * The overlay copies files from the source directory into the target path
+     * for better isolation. Heavy directories (node_modules, .venv, etc.) are
+     * copied in the background. Use the `ignore` option to exclude files/directories.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory
+     * @param options.target - Relative path in sandbox
+     * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
+     * @param options.strategy - Strategy to use ('copy' or 'smart')
+     * @param options.waitForCompletion - If true or options object, wait for background copy to complete
+     * @returns Overlay info with copy status
+     */
+    create(options: CreateOverlayOptions): Promise<OverlayInfo>;
+    /**
+     * List all overlays for the current sandbox
+     * @returns Array of overlay info
+     */
+    list(): Promise<OverlayInfo[]>;
+    /**
+     * Retrieve a specific overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay info
+     */
+    retrieve(id: string): Promise<OverlayInfo>;
+    /**
+     * Destroy (delete) an overlay
+     * @param id - Overlay ID
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Wait for an overlay's background copy to complete
+     *
+     * Polls the overlay status with exponential backoff until the copy
+     * is complete or fails. Throws an error if the copy fails or times out.
+     *
+     * @param id - Overlay ID
+     * @param options - Polling options
+     * @returns Overlay info with final copy status
+     * @throws Error if copy fails or times out
+     */
+    waitForCompletion(id: string, options?: WaitForCompletionOptions): Promise<OverlayInfo>;
+    /**
+     * Convert API response to OverlayInfo
+     */
+    private toOverlayInfo;
+    /**
+     * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
+     */
+    private validateStrategy;
+    /**
+     * Validate and return copy status, defaulting to 'pending' for unknown values
+     */
+    private validateCopyStatus;
+}
+
 /**
  * Server - Resource namespace for managed server operations
  */
@@ -1119,6 +1353,18 @@ interface ServerStartOptions {
     env_file?: string;
     /** Inline environment variables (merged with env_file if both provided) */
     environment?: Record<string, string>;
+    /** Requested port number (preallocated before start) */
+    port?: number;
+    /** If true, fail instead of auto-incrementing when port is taken */
+    strict_port?: boolean;
+    /** Whether to auto-start the server on daemon boot (default: true) */
+    autostart?: boolean;
+    /** Inline overlay to create before starting the server */
+    overlay?: Omit<CreateOverlayOptions, 'waitForCompletion'>;
+    /** Additional overlays to create before starting the server */
+    overlays?: Array<Omit<CreateOverlayOptions, 'waitForCompletion'>>;
+    /** Overlay IDs this server depends on (waits for copy completion) */
+    depends_on?: string[];
     /**
      * When to automatically restart the server:
      * - `never`: No automatic restart (default)
@@ -1164,6 +1410,18 @@ interface ServerStartOptions {
  *   restart_delay_ms: 2000,
  * });
  *
+ * // Start with inline overlay dependencies
+ * const server = await sandbox.server.start({
+ *   slug: 'web',
+ *   start: 'npm run dev',
+ *   path: '/app',
+ *   overlay: {
+ *     source: '/templates/nextjs',
+ *     target: 'app',
+ *     strategy: 'smart',
+ *   },
+ * });
+ *
  * // List all servers
  * const servers = await sandbox.server.list();
  *
@@ -1173,6 +1431,9 @@ interface ServerStartOptions {
  * // Stop a server (graceful shutdown with SIGTERM → SIGKILL)
  * await sandbox.server.stop('api');
  *
+ * // Delete a server config
+ * await sandbox.server.delete('api');
+ *
  * // Restart a server
  * await sandbox.server.restart('api');
  * ```
@@ -1200,6 +1461,7 @@ declare class Server {
     private listHandler;
     private retrieveHandler;
     private stopHandler;
+    private deleteHandler;
     private restartHandler;
     private updateStatusHandler;
     private logsHandler;
@@ -1208,6 +1470,7 @@ declare class Server {
         list: () => Promise<ServersListResponse>;
         retrieve: (slug: string) => Promise<ServerResponse>;
         stop: (slug: string) => Promise<ServerStopResponse | void>;
+        delete: (slug: string) => Promise<void>;
         restart: (slug: string) => Promise<ServerResponse>;
         updateStatus: (slug: string, status: ServerStatus) => Promise<void>;
         logs: (slug: string, options?: ServerLogsOptions) => Promise<ServerLogsResponse>;
@@ -1264,10 +1527,15 @@ declare class Server {
      */
     retrieve(slug: string): Promise<ServerInfo>;
     /**
-     * Stop a server by slug
+     * Stop a server by slug (non-destructive)
      * @param slug - The server slug
      */
     stop(slug: string): Promise<void>;
+    /**
+     * Delete a server config by slug (stops + removes persistence)
+     * @param slug - The server slug
+     */
+    delete(slug: string): Promise<void>;
     /**
      * Restart a server by slug
      * @param slug - The server slug
@@ -1955,30 +2223,99 @@ declare class Run {
 }
 
 /**
- * Child - Resource namespace for child sandbox operations
+ * Client Types
+ *
+ * Types specific to the gateway Sandbox client implementation.
+ * Core universal types are imported from ../types/universal-sandbox
  */
 
 /**
- * Child resource namespace for managing child sandboxes
- *
- * Child sandboxes are isolated environments within the parent sandbox,
- * each with their own filesystem. Available only in multi-tenant mode.
- *
- * @example
- * ```typescript
- * // Create a new child sandbox
- * const child = await sandbox.child.create();
- * console.log(child.url); // https://sandbox-12345.sandbox.computesdk.com
- *
- * // List all children
- * const all = await sandbox.child.list();
- *
- * // Get a specific child
- * const info = await sandbox.child.retrieve('sandbox-12345');
- *
- * // Delete a child sandbox
- * await sandbox.child.destroy('sandbox-12345');
- *
+ * Sandbox status types (client-specific, more limited than universal)
+ */
+type SandboxStatus = 'running' | 'stopped' | 'error';
+/**
+ * Provider-agnostic sandbox info (alias for SandboxInfo for backward compatibility)
+ */
+interface ProviderSandboxInfo {
+    /** Unique identifier for the sandbox */
+    id: string;
+    /** Provider hosting the sandbox */
+    provider: string;
+    /** Runtime environment in the sandbox */
+    runtime: Runtime;
+    /** Current status of the sandbox */
+    status: SandboxStatus;
+    /** When the sandbox was created */
+    createdAt: Date;
+    /** Execution timeout in milliseconds */
+    timeout: number;
+    /** Additional provider-specific metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Error thrown when a command exits with a non-zero status
+ */
+declare class CommandExitError extends Error {
+    result: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        error: boolean;
+    };
+    name: string;
+    constructor(result: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        error: boolean;
+    });
+}
+/**
+ * Type guard to check if an error is a CommandExitError
+ */
+declare function isCommandExitError(error: unknown): error is CommandExitError;
+
+/**
+ * Child - Resource namespace for child sandbox operations
+ */
+
+/**
+ * Child resource namespace for managing child sandboxes
+ *
+ * Child sandboxes are isolated environments within the parent sandbox,
+ * each with their own filesystem. Available only in multi-tenant mode.
+ *
+ * @example
+ * ```typescript
+ * // Create a new child sandbox
+ * const child = await sandbox.child.create({
+ *   directory: '/custom/path',
+ *   overlays: [
+ *     {
+ *       source: '/templates/nextjs',
+ *       target: 'app',
+ *       strategy: 'smart',
+ *     },
+ *   ],
+ *   servers: [
+ *     {
+ *       slug: 'web',
+ *       start: 'npm run dev',
+ *       path: '/app',
+ *     },
+ *   ],
+ * });
+ * console.log(child.url); // https://sandbox-12345.sandbox.computesdk.com
+ *
+ * // List all children
+ * const all = await sandbox.child.list();
+ *
+ * // Get a specific child
+ * const info = await sandbox.child.retrieve('sandbox-12345');
+ *
+ * // Delete a child sandbox
+ * await sandbox.child.destroy('sandbox-12345');
+ *
  * // Delete child and its files
  * await sandbox.child.destroy('sandbox-12345', { deleteFiles: true });
  * ```
@@ -1989,7 +2326,7 @@ declare class Child {
     private retrieveHandler;
     private destroyHandler;
     constructor(handlers: {
-        create: () => Promise<SandboxInfo>;
+        create: (options?: CreateSandboxOptions$1) => Promise<SandboxInfo>;
         list: () => Promise<SandboxesListResponse>;
         retrieve: (subdomain: string) => Promise<SandboxInfo>;
         destroy: (subdomain: string, deleteFiles: boolean) => Promise<void>;
@@ -1998,7 +2335,7 @@ declare class Child {
      * Create a new child sandbox
      * @returns Child sandbox info including URL and subdomain
      */
-    create(): Promise<SandboxInfo>;
+    create(options?: CreateSandboxOptions$1): Promise<SandboxInfo>;
     /**
      * List all child sandboxes
      * @returns Array of child sandbox info
@@ -2022,209 +2359,36 @@ declare class Child {
 }
 
 /**
- * Overlay - Resource namespace for filesystem overlay operations
- *
- * Overlays enable instant sandbox setup from template directories by copying
- * files directly for isolation, with heavy directories copied in the background.
- */
-/**
- * Options for waiting for overlay copy completion
- */
-interface WaitForCompletionOptions {
-    /** Maximum number of retry attempts (default: 60) */
-    maxRetries?: number;
-    /** Initial delay between retries in milliseconds (default: 500) */
-    initialDelayMs?: number;
-    /** Maximum delay between retries in milliseconds (default: 5000) */
-    maxDelayMs?: number;
-    /** Backoff multiplier for exponential backoff (default: 1.5) */
-    backoffFactor?: number;
-}
-/**
- * Strategy for creating an overlay
- * - 'copy': Full copy of all files (standard behavior)
- * - 'smart': Use symlinks for immutable packages (e.g. node_modules) for instant creation
- */
-type OverlayStrategy = 'copy' | 'smart';
-/**
- * Options for creating an overlay
- */
-interface CreateOverlayOptions {
-    /** Absolute path to source directory (template) */
-    source: string;
-    /** Relative path in sandbox where overlay will be mounted */
-    target: string;
-    /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
-    ignore?: string[];
-    /** Strategy to use (default: 'smart') */
-    strategy?: OverlayStrategy;
-    /** If true, wait for background copy to complete before returning (default: false) */
-    waitForCompletion?: boolean | WaitForCompletionOptions;
-}
-/**
- * Copy status for overlay background operations
- */
-type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
-/**
- * Statistics about an overlay
- */
-interface OverlayStats {
-    /** Number of copied files */
-    copiedFiles: number;
-    /** Number of copied directories (heavy dirs copied in background) */
-    copiedDirs: number;
-    /** Paths that were skipped (e.g., .git, ignored patterns) */
-    skipped: string[];
-}
-/**
- * Overlay information (client-side normalized type)
- */
-interface OverlayInfo {
-    /** Unique overlay identifier */
-    id: string;
-    /** Absolute path to source directory */
-    source: string;
-    /** Relative path in sandbox */
-    target: string;
-    /** Strategy used for the overlay */
-    strategy: OverlayStrategy;
-    /** When the overlay was created */
-    createdAt: string;
-    /** Statistics about the overlay */
-    stats: OverlayStats;
-    /** Copy status for background operations */
-    copyStatus: OverlayCopyStatus;
-    /** Error message if copy failed */
-    copyError?: string;
-}
-/**
- * API response for overlay operations (snake_case from server)
+ * Ready - Resource namespace for gateway readiness
  */
-interface OverlayResponse {
-    id: string;
-    source: string;
-    target: string;
-    strategy?: string;
-    created_at: string;
-    stats: {
-        copied_files: number;
-        copied_dirs: number;
-        skipped: string[];
-    };
-    copy_status: string;
-    copy_error?: string;
-}
+
 /**
- * API response for listing overlays
+ * Ready info returned by readiness endpoint
  */
-interface OverlayListResponse {
-    overlays: OverlayResponse[];
+interface ReadyInfo {
+    ready: boolean;
+    servers: ReadyResponse['servers'];
+    overlays: ReadyResponse['overlays'];
 }
 /**
- * Overlay resource namespace
+ * Ready resource namespace
  *
  * @example
  * ```typescript
- * // Create an overlay from a template directory
- * const overlay = await sandbox.filesystem.overlay.create({
- *   source: '/templates/nextjs',
- *   target: 'project',
- * });
- * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
- *
- * // Create an overlay and wait for background copy to complete
- * const overlay = await sandbox.filesystem.overlay.create({
- *   source: '/templates/nextjs',
- *   target: 'project',
- *   waitForCompletion: true, // blocks until copy is complete
- * });
- *
- * // Wait for an existing overlay's copy to complete
- * const overlay = await sandbox.filesystem.overlay.waitForCompletion('overlay-id');
- *
- * // List all overlays
- * const overlays = await sandbox.filesystem.overlay.list();
- *
- * // Get a specific overlay (useful for polling copy status)
- * const overlay = await sandbox.filesystem.overlay.retrieve('overlay-id');
- * if (overlay.copyStatus === 'complete') {
- *   console.log('Background copy finished!');
- * }
- *
- * // Delete an overlay
- * await sandbox.filesystem.overlay.destroy('overlay-id');
+ * const status = await sandbox.ready.get();
+ * console.log(status.ready);
+ * console.log(status.servers);
  * ```
  */
-declare class Overlay {
-    private createHandler;
-    private listHandler;
-    private retrieveHandler;
-    private destroyHandler;
+declare class Ready {
+    private getHandler;
     constructor(handlers: {
-        create: (options: CreateOverlayOptions) => Promise<OverlayResponse>;
-        list: () => Promise<OverlayListResponse>;
-        retrieve: (id: string) => Promise<OverlayResponse>;
-        destroy: (id: string) => Promise<void>;
+        get: () => Promise<ReadyResponse>;
     });
     /**
-     * Create a new overlay from a template directory
-     *
-     * The overlay copies files from the source directory into the target path
-     * for better isolation. Heavy directories (node_modules, .venv, etc.) are
-     * copied in the background. Use the `ignore` option to exclude files/directories.
-     *
-     * @param options - Overlay creation options
-     * @param options.source - Absolute path to source directory
-     * @param options.target - Relative path in sandbox
-     * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
-     * @param options.strategy - Strategy to use ('copy' or 'smart')
-     * @param options.waitForCompletion - If true or options object, wait for background copy to complete
-     * @returns Overlay info with copy status
-     */
-    create(options: CreateOverlayOptions): Promise<OverlayInfo>;
-    /**
-     * List all overlays for the current sandbox
-     * @returns Array of overlay info
-     */
-    list(): Promise<OverlayInfo[]>;
-    /**
-     * Retrieve a specific overlay by ID
-     *
-     * Useful for polling the copy status of an overlay.
-     *
-     * @param id - Overlay ID
-     * @returns Overlay info
-     */
-    retrieve(id: string): Promise<OverlayInfo>;
-    /**
-     * Destroy (delete) an overlay
-     * @param id - Overlay ID
-     */
-    destroy(id: string): Promise<void>;
-    /**
-     * Wait for an overlay's background copy to complete
-     *
-     * Polls the overlay status with exponential backoff until the copy
-     * is complete or fails. Throws an error if the copy fails or times out.
-     *
-     * @param id - Overlay ID
-     * @param options - Polling options
-     * @returns Overlay info with final copy status
-     * @throws Error if copy fails or times out
-     */
-    waitForCompletion(id: string, options?: WaitForCompletionOptions): Promise<OverlayInfo>;
-    /**
-     * Convert API response to OverlayInfo
-     */
-    private toOverlayInfo;
-    /**
-     * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
-     */
-    private validateStrategy;
-    /**
-     * Validate and return copy status, defaulting to 'pending' for unknown values
+     * Get readiness status for autostarted servers and overlays
      */
-    private validateCopyStatus;
+    get(): Promise<ReadyInfo>;
 }
 
 /**
@@ -2271,59 +2435,6 @@ declare function encodeBinaryMessage(message: any): ArrayBuffer;
  */
 declare function decodeBinaryMessage(buffer: ArrayBuffer | Uint8Array): any;
 
-/**
- * Client Types
- *
- * Types specific to the gateway Sandbox client implementation.
- * Core universal types are imported from ../types/universal-sandbox
- */
-
-/**
- * Sandbox status types (client-specific, more limited than universal)
- */
-type SandboxStatus = 'running' | 'stopped' | 'error';
-/**
- * Provider-agnostic sandbox info (alias for SandboxInfo for backward compatibility)
- */
-interface ProviderSandboxInfo {
-    /** Unique identifier for the sandbox */
-    id: string;
-    /** Provider hosting the sandbox */
-    provider: string;
-    /** Runtime environment in the sandbox */
-    runtime: Runtime;
-    /** Current status of the sandbox */
-    status: SandboxStatus;
-    /** When the sandbox was created */
-    createdAt: Date;
-    /** Execution timeout in milliseconds */
-    timeout: number;
-    /** Additional provider-specific metadata */
-    metadata?: Record<string, any>;
-}
-/**
- * Error thrown when a command exits with a non-zero status
- */
-declare class CommandExitError extends Error {
-    result: {
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-        error: boolean;
-    };
-    name: string;
-    constructor(result: {
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-        error: boolean;
-    });
-}
-/**
- * Type guard to check if an error is a CommandExitError
- */
-declare function isCommandExitError(error: unknown): error is CommandExitError;
-
 /**
  * ComputeSDK Client - Universal Sandbox Implementation
  *
@@ -2703,6 +2814,12 @@ interface ServerInfo {
     env_file?: string;
     /** Inline environment variables */
     environment?: Record<string, string>;
+    /** Whether to auto-start the server on daemon boot */
+    autostart?: boolean;
+    /** If true, port allocation is strict (no auto-increment) */
+    strict_port?: boolean;
+    /** Overlay IDs this server depends on */
+    depends_on?: string[];
     /** Auto-detected port number (populated when port monitor detects listening port) */
     port?: number;
     /** Generated URL from subdomain + port (populated when port is detected) */
@@ -2728,6 +2845,32 @@ interface ServerInfo {
     /** When the server was last updated */
     updated_at: string;
 }
+/**
+ * Ready server info returned by readiness endpoint
+ */
+interface ReadyServerInfo {
+    slug: string;
+    port?: number;
+    url?: string;
+    status: ServerStatus;
+}
+/**
+ * Ready overlay info returned by readiness endpoint
+ */
+interface ReadyOverlayInfo {
+    id: string;
+    source: string;
+    target: string;
+    copy_status: string;
+}
+/**
+ * Ready response (public endpoint)
+ */
+interface ReadyResponse {
+    ready: boolean;
+    servers: ReadyServerInfo[];
+    overlays: ReadyOverlayInfo[];
+}
 /**
  * Servers list response
  */
@@ -2933,6 +3076,7 @@ declare class Sandbox {
     readonly sessionToken: SessionToken;
     readonly magicLink: MagicLink;
     readonly signal: Signal;
+    readonly ready: Ready;
     readonly file: File;
     readonly env: Env;
     readonly auth: Auth;
@@ -3381,6 +3525,12 @@ declare class Sandbox {
      * @param options.path - Working directory (optional)
      * @param options.env_file - Path to .env file relative to path (optional)
      * @param options.environment - Inline environment variables (merged with env_file if both provided)
+     * @param options.port - Requested port (preallocated before start)
+     * @param options.strict_port - If true, fail instead of auto-incrementing when port is taken
+     * @param options.autostart - Auto-start on daemon boot (default: true)
+     * @param options.overlay - Inline overlay to create before starting
+     * @param options.overlays - Additional overlays to create before starting
+     * @param options.depends_on - Overlay IDs this server depends on
      * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
      * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
      * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
@@ -3407,6 +3557,18 @@ declare class Sandbox {
      *   restart_delay_ms: 2000,
      *   stop_timeout_ms: 5000,
      * });
+     *
+     * // With inline overlay dependencies
+     * await sandbox.startServer({
+     *   slug: 'web',
+     *   start: 'npm run dev',
+     *   path: '/app',
+     *   overlay: {
+     *     source: '/templates/nextjs',
+     *     target: 'app',
+     *     strategy: 'smart',
+     *   },
+     * });
      * ```
      */
     startServer(options: {
@@ -3416,6 +3578,12 @@ declare class Sandbox {
         path?: string;
         env_file?: string;
         environment?: Record<string, string>;
+        port?: number;
+        strict_port?: boolean;
+        autostart?: boolean;
+        overlay?: Omit<CreateOverlayOptions, 'waitForCompletion'>;
+        overlays?: Array<Omit<CreateOverlayOptions, 'waitForCompletion'>>;
+        depends_on?: string[];
         restart_policy?: RestartPolicy;
         max_restarts?: number;
         restart_delay_ms?: number;
@@ -3427,10 +3595,15 @@ declare class Sandbox {
      */
     getServer(slug: string): Promise<ServerResponse>;
     /**
-     * Stop a managed server
+     * Stop a managed server (non-destructive)
      * @param slug - Server slug
      */
     stopServer(slug: string): Promise<ServerStopResponse>;
+    /**
+     * Delete a managed server configuration
+     * @param slug - Server slug
+     */
+    deleteServer(slug: string): Promise<void>;
     /**
      * Restart a managed server
      * @param slug - Server slug
@@ -3450,10 +3623,14 @@ declare class Sandbox {
      * @param status - New server status
      */
     updateServerStatus(slug: string, status: ServerStatus): Promise<ServerStatusUpdateResponse>;
+    /**
+     * Get readiness status for autostarted servers and overlays
+     */
+    getReady(): Promise<ReadyResponse>;
     /**
      * Create a new sandbox environment
      */
-    createSandbox(): Promise<SandboxInfo>;
+    createSandbox(options?: CreateSandboxOptions$1): Promise<SandboxInfo>;
     /**
      * List all sandboxes
      */
@@ -3584,6 +3761,28 @@ declare class Sandbox {
     disconnect(): Promise<void>;
 }
 
+/**
+ * Helpers for building setup payloads used by COMPUTESDK_SETUP_B64 or POST /sandboxes
+ */
+
+type SetupOverlayConfig = Omit<CreateOverlayOptions, 'waitForCompletion'>;
+interface SetupPayload {
+    overlays?: SetupOverlayConfig[];
+    servers?: ServerStartOptions[];
+}
+interface BuildSetupPayloadOptions {
+    overlays?: CreateOverlayOptions[];
+    servers?: ServerStartOptions[];
+}
+/**
+ * Build a setup payload for COMPUTESDK_SETUP_B64 or POST /sandboxes
+ */
+declare const buildSetupPayload: (options: BuildSetupPayloadOptions) => SetupPayload;
+/**
+ * Build and base64-encode a setup payload for COMPUTESDK_SETUP_B64
+ */
+declare const encodeSetupPayload: (options: BuildSetupPayloadOptions) => string;
+
 /**
  * Unified Provider Configuration
  *
@@ -3744,6 +3943,9 @@ interface CreateSandboxOptions {
     envs?: Record<string, string>;
     name?: string;
     namespace?: string;
+    directory?: string;
+    overlays?: SetupOverlayConfig[];
+    servers?: ServerStartOptions[];
     /** Docker image to use for the sandbox (for infrastructure providers like Railway) */
     image?: string;
     /** Provider-specific snapshot to create from (e.g., Vercel snapshots) */
@@ -3803,6 +4005,27 @@ declare class ComputeManager {
     sandbox: {
         /**
          * Create a new sandbox
+         *
+         * @example
+         * ```typescript
+         * const sandbox = await compute.sandbox.create({
+         *   directory: '/custom/path',
+         *   overlays: [
+         *     {
+         *       source: '/templates/nextjs',
+         *       target: 'app',
+         *       strategy: 'smart',
+         *     },
+         *   ],
+         *   servers: [
+         *     {
+         *       slug: 'web',
+         *       start: 'npm run dev',
+         *       path: '/app',
+         *     },
+         *   ],
+         * });
+         * ```
          */
         create: (options?: CreateSandboxOptions) => Promise<Sandbox>;
         /**
@@ -3942,4 +4165,4 @@ declare const PROVIDER_ENV_VARS: {
     readonly namespace: readonly ["NSC_TOKEN"];
 };
 
-export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, type WebSocketConstructor, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };
+export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, type SetupOverlayConfig, type SetupPayload, SignalService, TerminalInstance, type WebSocketConstructor, autoConfigureCompute, buildProviderHeaders, buildSetupPayload, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, encodeSetupPayload, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };