@cloudflare/sandbox 0.10.1 → 0.10.3

package/dist/{sandbox-BVgScWy9.d.ts → sandbox-CwcSm_60.d.ts}

@@ -24,21 +24,29 @@ interface DesktopProcessHealth {
   uptime?: number;
 }
 type DesktopImageFormat = 'png' | 'jpeg' | 'webp';
-interface DesktopScreenshotRequest {
-  format?: 'base64';
+interface DesktopScreenshotOptions {
+  /**
+   * How the SDK returns the screenshot payload to the caller.
+   * - `'base64'` (default): `data` is a base64-encoded string (also the wire format).
+   * - `'bytes'`: client-side convenience that base64-decodes the wire payload
+   *   into a `Uint8Array` before returning. The wire/server contract is
+   *   always base64.
+   */
+  format?: 'base64' | 'bytes';
   imageFormat?: DesktopImageFormat;
   quality?: number;
   showCursor?: boolean;
 }
-interface DesktopScreenshotRegionRequest extends DesktopScreenshotRequest {
-  region: DesktopScreenshotRegion;
-}
 interface DesktopScreenshotRegion {
   x: number;
   y: number;
   width: number;
   height: number;
 }
+/**
+ * Screenshot payload returned to the SDK caller when `format` is `'base64'`
+ * (the default). Matches the wire shape sent by the container.
+ */
 interface DesktopScreenshotResult {
   success: boolean;
   data: string;
@@ -46,6 +54,14 @@ interface DesktopScreenshotResult {
   width: number;
   height: number;
 }
+/**
+ * Screenshot payload returned to the SDK caller when `format: 'bytes'` is
+ * requested. The SDK client decodes the base64 wire payload into a
+ * `Uint8Array`; the server/wire contract is unchanged.
+ */
+interface DesktopScreenshotBytesResult extends Omit<DesktopScreenshotResult, 'data'> {
+  data: Uint8Array;
+}
 type DesktopMouseButton = 'left' | 'right' | 'middle';
 type DesktopScrollDirection = 'up' | 'down' | 'left' | 'right';
 interface DesktopCursorPosition {
@@ -568,6 +584,12 @@ interface PortWatchRequest extends PortCheckRequest {
   interval?: number;
 }
 interface ProcessOptions extends BaseExecOptions {
+  /**
+   * Optional session ID to run the background process in.
+   *
+   * When omitted, the sandbox's default execution policy applies.
+   */
+  sessionId?: string;
   /**
    * Custom process ID for later reference
    * If not provided, a UUID will be generated
@@ -697,6 +719,12 @@ interface LogEvent {
   exitCode?: number;
 }
 interface StreamOptions extends BaseExecOptions {
+  /**
+   * Optional session ID to run the streaming command in.
+   *
+   * When omitted, the sandbox's default execution policy applies.
+   */
+  sessionId?: string;
   /**
    * Buffer size for streaming output
    */
@@ -755,6 +783,16 @@ interface SandboxOptions {
    * Default: false
    */
   keepAlive?: boolean;
+  /**
+   * When true (the default), implicit operations automatically create and reuse
+   * a persistent default shell session. Set to false to run implicit top-level
+   * operations sessionlessly, where each command spawns a fresh process with no
+   * shared shell state. Explicit per-call session IDs continue to work normally
+   * when this is false.
+   *
+   * Default: true
+   */
+  enableDefaultSession?: boolean;
   /**
    * Normalize sandbox ID to lowercase for preview URL compatibility
    *
@@ -949,6 +987,12 @@ interface FileInfo {
 interface ListFilesOptions {
   recursive?: boolean;
   includeHidden?: boolean;
+  /**
+   * Optional session ID used to resolve relative paths and execution context.
+   *
+   * When omitted, the sandbox's default execution policy applies.
+   */
+  sessionId?: string;
 }
 interface ListFilesResult {
   success: boolean;
@@ -1146,6 +1190,8 @@ interface ProcessLogsResult {
 }
 interface ProcessCleanupResult {
   success: boolean;
+  message?: string;
+  killedCount?: number;
   cleanedCount: number;
   timestamp: string;
 }
@@ -1180,8 +1226,8 @@ interface ExecutionSession {
   exec(command: string, options?: ExecOptions): Promise<ExecResult>;
   execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
   startProcess(command: string, options?: ProcessOptions): Promise<Process>;
-  listProcesses(): Promise<Process[]>;
-  getProcess(id: string): Promise<Process | null>;
+  listProcesses(sessionId?: string): Promise<Process[]>;
+  getProcess(id: string, sessionId?: string): Promise<Process | null>;
   killProcess(id: string, signal?: string): Promise<void>;
   killAllProcesses(): Promise<number>;
   cleanupCompletedProcesses(): Promise<number>;
@@ -1359,10 +1405,10 @@ interface RemoteMountBucketOptions {
   /**
    * Optional prefix/subdirectory within the bucket to mount.
    *
-   * When specified, only the contents under this prefix will be visible
-   * at the mount point, enabling multi-tenant isolation within a single bucket.
+   * When specified, only the contents under this prefix are visible at the
+   * mount point, scoping the mount to a subdirectory of the bucket.
    *
-   * Must start with '/' (e.g., '/sessions/user123' or '/data/uploads/')
+   * Must start with '/' (e.g., '/workspaces/project123' or '/data/uploads/')
    */
   prefix?: string;
 }
@@ -1392,14 +1438,41 @@ interface LocalMountBucketOptions {
   readOnly?: boolean;
 }
 /**
- * Options for mounting a bucket — either remote (s3fs-FUSE) or local (R2 binding sync)
+ * Options for mounting an R2 binding via credential-less egress interception.
  */
-type MountBucketOptions = RemoteMountBucketOptions | LocalMountBucketOptions;
+interface R2BindingMountBucketOptions {
+  /**
+   * Must not be set — distinguishes this variant from RemoteMountBucketOptions.
+   */
+  endpoint?: never;
+  /**
+   * Optional prefix/subdirectory within the bucket to mount.
+   *
+   * When specified, only the contents under this prefix will be visible
+   * at the mount point.
+   */
+  prefix?: string;
+  /**
+   * Mount filesystem as read-only
+   * Default: false
+   */
+  readOnly?: boolean;
+  /**
+   * Advanced: Override or extend s3fs options.
+   * Provider defaults for R2 are still applied automatically.
+   */
+  s3fsOptions?: string[];
+}
+/**
+ * Options for mounting a bucket — remote (s3fs-FUSE), local (R2 binding sync),
+ * or R2 egress (credential-less s3fs via egress interception).
+ */
+type MountBucketOptions = RemoteMountBucketOptions | LocalMountBucketOptions | R2BindingMountBucketOptions;
 interface ISandbox {
   exec(command: string, options?: ExecOptions): Promise<ExecResult>;
   startProcess(command: string, options?: ProcessOptions): Promise<Process>;
-  listProcesses(): Promise<Process[]>;
-  getProcess(id: string): Promise<Process | null>;
+  listProcesses(sessionId?: string): Promise<Process[]>;
+  getProcess(id: string, sessionId?: string): Promise<Process | null>;
   killProcess(id: string, signal?: string): Promise<void>;
   killAllProcesses(): Promise<number>;
   execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
@@ -1586,6 +1659,7 @@ interface SandboxCommandsAPI {
     timeoutMs?: number;
     env?: Record<string, string | undefined>;
     cwd?: string;
+    origin?: 'user' | 'internal';
   }): Promise<{
     success: boolean;
     exitCode: number;
@@ -1598,6 +1672,7 @@ interface SandboxCommandsAPI {
     timeoutMs?: number;
     env?: Record<string, string | undefined>;
     cwd?: string;
+    origin?: 'user' | 'internal';
   }): Promise<ReadableStream<Uint8Array>>;
 }
 interface SandboxFilesAPI {
@@ -1714,8 +1789,20 @@ interface SandboxDesktopAPI {
   }): Promise<DesktopStartResult>;
   stop(): Promise<DesktopStopResult>;
   status(): Promise<DesktopStatusResult>;
-  screenshot(options?: DesktopScreenshotRequest): Promise<DesktopScreenshotResult>;
-  screenshotRegion(request: DesktopScreenshotRegionRequest): Promise<DesktopScreenshotResult>;
+  screenshot(options?: DesktopScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<DesktopScreenshotResult>;
+  screenshot(options: DesktopScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<DesktopScreenshotBytesResult>;
+  screenshot(options?: DesktopScreenshotOptions): Promise<DesktopScreenshotResult | DesktopScreenshotBytesResult>;
+  screenshotRegion(region: DesktopScreenshotRegion, options?: DesktopScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<DesktopScreenshotResult>;
+  screenshotRegion(region: DesktopScreenshotRegion, options: DesktopScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<DesktopScreenshotBytesResult>;
+  screenshotRegion(region: DesktopScreenshotRegion, options?: DesktopScreenshotOptions): Promise<DesktopScreenshotResult | DesktopScreenshotBytesResult>;
   click(x: number, y: number, options?: {
     button?: DesktopMouseButton;
     clickCount?: number;
@@ -1737,18 +1824,47 @@ interface SandboxDesktopAPI {
   scroll(x: number, y: number, direction: DesktopScrollDirection, amount?: number): Promise<void>;
   getCursorPosition(): Promise<DesktopCursorPosition>;
   type(text: string, options?: {
-    delay?: number;
+    delayMs?: number;
   }): Promise<void>;
   press(key: string): Promise<void>;
   keyDown(key: string): Promise<void>;
   keyUp(key: string): Promise<void>;
   getScreenSize(): Promise<DesktopScreenSize>;
-  getProcessStatus(name: string): Promise<DesktopStatusResult>;
+  getProcessStatus(name: string): Promise<DesktopProcessHealth>;
 }
 interface SandboxWatchAPI {
   watch(request: WatchRequest): Promise<ReadableStream<Uint8Array>>;
   checkChanges(request: CheckChangesRequest): Promise<CheckChangesResult>;
 }
+/**
+ * Public-facing tunnel record.
+ *
+ * Today only quick tunnels (`*.trycloudflare.com`) are supported. Future
+ * PRs will add named tunnels, which will carry a `name: string` field;
+ * `TunnelInfo` will then become a discriminated union keyed on the
+ * presence of `name`. The quick variant declares `name?: never` so the
+ * narrowing works without a breaking change here.
+ */
+interface TunnelInfo {
+  id: string;
+  port: number;
+  url: string;
+  hostname: string;
+  createdAt: string;
+  /** Reserved for the named-tunnel variant in a future PR. */
+  name?: never;
+}
+interface SandboxTunnelsAPI {
+  /** Spawn `cloudflared tunnel --url`. No credentials required. */
+  runQuickTunnel(id: string, port: number): Promise<TunnelInfo>;
+  /** Stop the cloudflared process for the given tunnel id. */
+  destroyTunnel(id: string): Promise<{
+    success: true;
+    id: string;
+  }>;
+  /** List tunnels currently running inside the container. */
+  listTunnels(): Promise<TunnelInfo[]>;
+}
 //#endregion
 //#region src/clients/types.d.ts
 /**
@@ -1955,7 +2071,7 @@ declare abstract class BaseHttpClient {
  * The container creates/extracts squashfs archives locally.
  * R2 upload/download is handled by the Sandbox DO, not by this client.
  */
-declare class BackupClient extends BaseHttpClient {
+declare class BackupClient extends BaseHttpClient implements SandboxBackupAPI {
   /**
    * Tell the container to create a squashfs archive from a directory.
    * @param dir - Directory to back up
@@ -1990,7 +2106,7 @@ interface ExecuteResponse extends BaseApiResponse {
 /**
  * Client for command execution operations
  */
-declare class CommandClient extends BaseHttpClient {
+declare class CommandClient extends BaseHttpClient implements SandboxCommandsAPI {
   /**
    * Execute a command and return the complete result
    * @param command - The command to execute
@@ -2118,16 +2234,12 @@ interface Desktop {
   keyDown(key: KeyInput): Promise<void>;
   keyUp(key: KeyInput): Promise<void>;
   getScreenSize(): Promise<ScreenSizeResponse>;
-  getProcessStatus(name: string): Promise<BaseApiResponse & {
-    running: boolean;
-    pid?: number;
-    uptime?: number;
-  }>;
+  getProcessStatus(name: string): Promise<DesktopProcessHealth>;
 }
 /**
  * Client for desktop environment lifecycle, input, and screen operations
  */
-declare class DesktopClient extends BaseHttpClient {
+declare class DesktopClient extends BaseHttpClient implements SandboxDesktopAPI {
   /**
    * Start the desktop environment with optional resolution and DPI.
    */
@@ -2231,11 +2343,7 @@ declare class DesktopClient extends BaseHttpClient {
   /**
    * Get health status for a specific desktop process.
    */
-  getProcessStatus(name: string): Promise<BaseApiResponse & {
-    running: boolean;
-    pid?: number;
-    uptime?: number;
-  }>;
+  getProcessStatus(name: string): Promise<DesktopProcessHealth>;
 }
 //#endregion
 //#region src/clients/file-client.d.ts
@@ -2271,7 +2379,7 @@ interface FileOperationRequest extends SessionRequest {
 /**
  * Client for file system operations
  */
-declare class FileClient extends BaseHttpClient {
+declare class FileClient extends BaseHttpClient implements SandboxFilesAPI {
   /**
    * Create a directory
    * @param path - Directory path to create
@@ -2376,7 +2484,7 @@ interface GitCheckoutRequest extends SessionRequest {
 /**
  * Client for Git repository operations
  */
-declare class GitClient extends BaseHttpClient {
+declare class GitClient extends BaseHttpClient implements SandboxGitAPI {
   private static readonly REQUEST_TIMEOUT_BUFFER_MS;
   constructor(options?: HttpClientOptions);
   /**
@@ -2402,7 +2510,7 @@ interface ExecutionCallbacks {
   onResult?: (result: Result) => void | Promise<void>;
   onError?: (error: ExecutionError) => void | Promise<void>;
 }
-declare class InterpreterClient extends BaseHttpClient {
+declare class InterpreterClient extends BaseHttpClient implements SandboxInterpreterAPI {
   private readonly maxRetries;
   private readonly retryDelayMs;
   createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
@@ -2434,7 +2542,7 @@ interface UnexposePortRequest {
 /**
  * Client for port management and preview URL operations
  */
-declare class PortClient extends BaseHttpClient {
+declare class PortClient extends BaseHttpClient implements SandboxPortsAPI {
   /**
    * Expose a port and get a preview URL
    * @param port - Port number to expose
@@ -2465,7 +2573,7 @@ declare class PortClient extends BaseHttpClient {
 /**
  * Client for background process management
  */
-declare class ProcessClient extends BaseHttpClient {
+declare class ProcessClient extends BaseHttpClient implements SandboxProcessesAPI {
   /**
    * Start a background process
    * @param command - Command to execute as a background process
@@ -2562,7 +2670,7 @@ interface DeleteSessionResponse extends BaseApiResponse {
 /**
  * Client for health checks and utility operations
  */
-declare class UtilityClient extends BaseHttpClient {
+declare class UtilityClient extends BaseHttpClient implements SandboxUtilsAPI {
   /**
    * Ping the sandbox to check if it's responsive
    */
@@ -2586,6 +2694,9 @@ declare class UtilityClient extends BaseHttpClient {
    * Returns the version embedded in the Docker image during build
    */
   getVersion(): Promise<string>;
+  listSessions(): Promise<{
+    sessions: string[];
+  }>;
 }
 //#endregion
 //#region src/clients/watch-client.d.ts
@@ -2596,7 +2707,7 @@ declare class UtilityClient extends BaseHttpClient {
  * @internal This client is used internally by the SDK.
  * Users should use `sandbox.watch()` or `sandbox.checkChanges()` instead.
  */
-declare class WatchClient extends BaseHttpClient {
+declare class WatchClient extends BaseHttpClient implements SandboxWatchAPI {
   /**
    * Check whether a path changed since a previously returned version.
    */
@@ -2640,6 +2751,13 @@ declare class SandboxClient {
   readonly utils: UtilityClient;
   readonly desktop: DesktopClient;
   readonly watch: WatchClient;
+  /**
+   * Tunnels are RPC-only — the route-based transport does not implement them.
+   * This getter exists so the `PublicKeys<SandboxClient> satisfies
+   * PublicKeys<SandboxAPI>` compile-time check holds. Calling any method on
+   * the returned proxy throws a clear `RPC transport required` error.
+   */
+  readonly tunnels: never;
   private transport;
   constructor(options: HttpClientOptions);
   /**
@@ -2686,6 +2804,25 @@ interface ContainerControlConnectionOptions {
    * `WebSocketTransport`. Set to 0 to disable retries.
    */
   retryTimeoutMs?: number;
+  /**
+   * Optional `localMain` exposed to the container side of the capnweb
+   * session. The container reaches it via
+   * `session.getRemoteMain()` and uses it for control-plane callbacks
+   * (e.g. notifying the DO when a tunnel's cloudflared process has
+   * exited). When omitted, the container sees an empty remote main.
+   */
+  localMain?: any;
+  /**
+   * Invoked when an active WebSocket transitions to closed/errored.
+   * Fired at most once per successful connection from the WS event
+   * handlers in `doConnect`. Gives owners a synchronous teardown
+   * signal so recovery doesn't depend on a periodic poller running
+   * inside what may be an idle isolate.
+   *
+   * Not fired for `doConnect` failures (the rejected `connect()`
+   * promise is the signal in that case) nor for `disconnect()`.
+   */
+  onClose?: () => void;
 }
 //#endregion
 //#region src/container-control/client.d.ts
@@ -2742,13 +2879,6 @@ declare class ContainerControlClient {
   private busyPollTimer;
   /** Tracks whether we currently believe the session is busy. */
   private busy;
-  /**
-   * Set the first time the poller observes `conn.isConnected() === true`,
-   * cleared in `destroyConnection()`. Lets us distinguish "the WebSocket
-   * upgrade is still in progress" (don't tear down) from "we were
-   * connected and the peer went away" (do tear down).
-   */
-  private wasEverConnected;
   constructor(options: ContainerControlClientOptions);
   /**
    * Return the current connection, creating one when the client is disconnected.
@@ -2787,6 +2917,7 @@ declare class ContainerControlClient {
   get backup(): SandboxBackupAPI;
   get desktop(): SandboxDesktopAPI;
   get watch(): SandboxWatchAPI;
+  get tunnels(): SandboxTunnelsAPI;
   get interpreter(): SandboxInterpreterAPI;
   /**
    * Update the 503 upgrade-retry budget. Applies to the current connection
@@ -2800,6 +2931,13 @@ declare class ContainerControlClient {
   disconnect(): void;
 }
 //#endregion
+//#region src/tunnels/tunnels-handler.d.ts
+interface TunnelsHandler {
+  get(port: number): Promise<TunnelInfo>;
+  list(): Promise<TunnelInfo[]>;
+  destroy(portOrInfo: number | TunnelInfo): Promise<void>;
+}
+//#endregion
 //#region src/sandbox.d.ts
 type SandboxConfiguration = {
   sandboxName?: {
@@ -2818,6 +2956,9 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   client: SandboxClient | ContainerControlClient;
   private codeInterpreter;
   private sandboxName;
+  private tunnelsHandler;
+  private tunnelExitHandler;
+  private readonly controlCallback;
   private normalizeId;
   private defaultSession;
   private containerGeneration;
@@ -2887,9 +3028,16 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Dispatch method for desktop operations.
    * Called by the client-side proxy created in getSandbox() to provide
    * the `sandbox.desktop.status()` API without relying on RPC pipelining
-   * through property getters.
+   * through property getters which is broken when using vite-plugin.
    */
   callDesktop(method: string, args: unknown[]): Promise<unknown>;
+  /**
+   * Dispatch method for tunnel operations.
+   * Called by the client-side proxy created in getSandbox() to provide
+   * the `sandbox.tunnels` API without relying on RPC pipelining
+   * through property getters which is broken when using vite-plugin.
+   */
+  callTunnels(method: string, args: unknown[]): Promise<unknown>;
   /**
    * Compute the transport retry budget from current container timeouts.
    *
@@ -2917,29 +3065,9 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   setSleepAfter(sleepAfter: string | number): Promise<void>;
   setKeepAlive(keepAlive: boolean): Promise<void>;
   setEnvVars(envVars: Record<string, string | undefined>): Promise<void>;
-  /**
-   * RPC method to configure container startup timeouts. Idempotent once
-   * the values have been persisted: re-applying the same timeout set is a
-   * no-op. The transport retry budget is recomputed only when at least
-   * one timeout actually changes. Storage is written before the in-memory
-   * mirror and derived state are updated.
-   */
   setContainerTimeouts(timeouts: NonNullable<SandboxOptions['containerTimeouts']>): Promise<void>;
-  /**
-   * RPC method to set the transport protocol. Idempotent once the value
-   * has been persisted: re-applying the same transport is a no-op.
-   * Storage is written before the in-memory state and client are updated.
-   */
   setTransport(transport: SandboxTransport): Promise<void>;
-  /**
-   * Validate a timeout value is within acceptable range
-   * Throws error if invalid - used for user-provided values
-   */
   private validateTimeout;
-  /**
-   * Get default timeouts with env var fallbacks and validation
-   * Precedence: SDK defaults < Env vars < User config
-   */
   private getDefaultTimeouts;
   /**
    * Mount an S3-compatible bucket as a local directory.
@@ -2959,6 +3087,13 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Local dev mount: bidirectional sync via R2 binding + file/watch APIs
    */
   private mountBucketLocal;
+  private getR2EgressParams;
+  private validateR2EgressS3fsOptions;
+  /**
+   * Credential-less R2 mount: egress interception routes s3fs requests to the
+   * R2 binding. No S3 credentials are needed in the container or Worker env.
+   */
+  private mountBucketR2Egress;
   /**
    * Production mount: S3FS-FUSE inside the container
    */
@@ -2971,7 +3106,11 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    */
   unmountBucket(mountPath: string): Promise<void>;
   /**
-   * Validate mount options
+   * Shared validation for mount path (absolute, not already in use).
+   */
+  private validateMountPath;
+  /**
+   * Validate mount options for remote (FUSE) mounts
    */
   private validateMountOptions;
   /**
@@ -2991,6 +3130,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Execute S3FS mount command
    */
   private executeS3FSMount;
+  private unmountTrackedFuseMount;
   /**
    * In-flight `destroy()` promise. While set, concurrent callers coalesce
    * onto the same teardown instead of triggering a second one. Cleared when
@@ -3116,7 +3256,24 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * yet observed."
    */
   private capturePlacementId;
+  private resolveExecution;
+  private validateExplicitSessionId;
+  private serializeExecutionContext;
+  private getPublicExecutionSessionId;
+  /**
+   * Resolves the session ID to annotate returned Process objects.
+   *
+   * Unlike `resolveExecution`, this is synchronous and never creates a
+   * session. When the default session hasn't been established yet, it returns
+   * `undefined` rather than triggering session creation. The resolved value is
+   * only used to populate `Process.sessionId` on the returned object — it is
+   * never sent to the container API.
+   */
+  private getProcessSessionBinding;
+  private resolveExecutionEnv;
+  private buildExecutionRequestOptions;
   exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  execWithSessionToken(command: string, sessionId: string, options?: ExecOptions): Promise<ExecResult>;
   /**
    * Execute an infrastructure command (backup, mount, env setup, etc.)
    * tagged with origin: 'internal' so logging demotes it to debug level.
@@ -3181,6 +3338,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     processId: string;
   }>;
   execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  execStreamWithSessionToken(command: string, sessionId: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
   /**
    * Internal session-aware execStream implementation
    */
@@ -3243,10 +3401,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   readFileStream(path: string, options?: {
     sessionId?: string;
   }): Promise<ReadableStream<Uint8Array>>;
-  listFiles(path: string, options?: {
-    recursive?: boolean;
-    includeHidden?: boolean;
-  }): Promise<ListFilesResult>;
+  listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
   exists(path: string, sessionId?: string): Promise<FileExistsResult>;
   /**
    * Get the noVNC preview URL for browser-based desktop viewing.
@@ -3335,6 +3490,33 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     port: number;
     status: "active" | "inactive";
   }[]>;
+  /**
+   * Namespaced tunnel API. Quick tunnels are zero-config preview URLs
+   * backed by Cloudflare's trycloudflare service.
+   *
+   * - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
+   *   `port` if one exists in DO storage, otherwise spawns a fresh
+   *   cloudflared process and persists the record.
+   * - `tunnels.list()` — records currently known to this sandbox, from
+   *   DO storage.
+   * - `tunnels.destroy(portOrInfo)` — tear down by port number or by
+   *   the record returned from `get()`.
+   *
+   * Storage is cleared on container restart (`onStart`), so URLs do
+   * not survive a container restart — the next `get(port)` call will
+   * spawn a fresh tunnel with a new URL.
+   *
+   * Requires the RPC transport. Calling this on a route-based transport
+   * throws "RPC transport required".
+   */
+  get tunnels(): TunnelsHandler;
+  /**
+   * Lazily construct both the public tunnels handler and its sibling
+   * exit-handler callback. Called from the `tunnels` getter on first
+   * access and on every access after a transport swap clears both
+   * fields.
+   */
+  private ensureTunnelsBuilt;
   isPortExposed(port: number): Promise<boolean>;
   validatePortToken(port: number, token: string): Promise<boolean>;
   private validateCustomToken;
@@ -3527,7 +3709,8 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * unsquashfs for extraction instead of squashfuse + fuse-overlayfs.
    */
   private doRestoreBackupLocal;
+  private configureR2EgressOutbound;
 }
 //#endregion
-export { BackupOptions as $, DesktopStopResponse as A, ProcessStartResult as At, ExecuteResponse as B, WatchOptions as Bt, ClickOptions as C, Process as Ct, DesktopStartOptions as D, ProcessListResult as Dt, DesktopClient as E, ProcessKillResult as Et, ScreenshotRegion as F, SandboxTransport as Ft, HttpClientOptions as G, CodeContext as Gt, BaseApiResponse as H, isProcess as Ht, ScreenshotResponse as I, SessionOptions as It, SessionRequest as J, ExecutionResult as Jt, RequestConfig as K, CreateContextOptions as Kt, ScrollDirection as L, StreamOptions as Lt, ScreenSizeResponse as M, RemoteMountBucketOptions as Mt, ScreenshotBytesResponse as N, RestoreBackupResult as Nt, DesktopStartResponse as O, ProcessLogsResult as Ot, ScreenshotOptions as P, SandboxOptions as Pt, StartProcessRequest as Q, TypeOptions as R, WaitForLogResult as Rt, WriteFileRequest as S, PortListResult as St, Desktop as T, ProcessInfoResult as Tt, ContainerStub as U, isProcessStatus as Ut, BackupClient as V, isExecResult as Vt, ErrorResponse as W, PtyOptions as Wt, ExecuteRequest as X, SandboxInterpreterAPI as Y, RunCodeOptions as Yt, ExposePortRequest as Z, GitClient as _, LocalMountBucketOptions as _t, CreateSessionRequest as a, DirectoryBackup as at, MkdirRequest as b, PortCloseResult as bt, DeleteSessionResponse as c, ExecResult as ct, ProcessClient as d, FileMetadata as dt, BaseExecOptions as et, PortClient as f, FileStreamEvent as ft, GitCheckoutRequest as g, ListFilesOptions as gt, InterpreterClient as h, ISandbox as ht, CommandsResponse as i, CheckChangesResult as it, KeyInput as j, ProcessStatus as jt, DesktopStatusResponse as k, ProcessOptions as kt, PingResponse as l, ExecutionSession as lt, ExecutionCallbacks as m, GitCheckoutResult as mt, getSandbox as n, BucketProvider as nt, CreateSessionResponse as o, ExecEvent as ot, UnexposePortRequest as p, FileWatchSSEEvent as pt, ResponseHandler as q, Execution as qt, SandboxClient as r, CheckChangesOptions as rt, DeleteSessionRequest as s, ExecOptions as st, Sandbox as t, BucketCredentials as tt, UtilityClient as u, FileChunk as ut, FileClient as v, LogEvent as vt, CursorPositionResponse as w, ProcessCleanupResult as wt, ReadFileRequest as x, PortExposeResult as xt, FileOperationRequest as y, MountBucketOptions as yt, CommandClient as z, WaitForPortOptions as zt };
-//# sourceMappingURL=sandbox-BVgScWy9.d.ts.map
+export { StartProcessRequest as $, DesktopStopResponse as A, ProcessOptions as At, ExecuteResponse as B, WaitForPortOptions as Bt, ClickOptions as C, PortListResult as Ct, DesktopStartOptions as D, ProcessKillResult as Dt, DesktopClient as E, ProcessInfoResult as Et, ScreenshotRegion as F, SandboxOptions as Ft, HttpClientOptions as G, PtyOptions as Gt, BaseApiResponse as H, isExecResult as Ht, ScreenshotResponse as I, SandboxTransport as It, SessionRequest as J, Execution as Jt, RequestConfig as K, CodeContext as Kt, ScrollDirection as L, SessionOptions as Lt, ScreenSizeResponse as M, ProcessStatus as Mt, ScreenshotBytesResponse as N, RemoteMountBucketOptions as Nt, DesktopStartResponse as O, ProcessListResult as Ot, ScreenshotOptions as P, RestoreBackupResult as Pt, ExposePortRequest as Q, TypeOptions as R, StreamOptions as Rt, WriteFileRequest as S, PortExposeResult as St, Desktop as T, ProcessCleanupResult as Tt, ContainerStub as U, isProcess as Ut, BackupClient as V, WatchOptions as Vt, ErrorResponse as W, isProcessStatus as Wt, TunnelInfo as X, RunCodeOptions as Xt, SandboxInterpreterAPI as Y, ExecutionResult as Yt, ExecuteRequest as Z, GitClient as _, ListFilesOptions as _t, CreateSessionRequest as a, CheckChangesResult as at, MkdirRequest as b, MountBucketOptions as bt, DeleteSessionResponse as c, ExecOptions as ct, ProcessClient as d, FileChunk as dt, BackupOptions as et, PortClient as f, FileMetadata as ft, GitCheckoutRequest as g, ISandbox as gt, InterpreterClient as h, GitCheckoutResult as ht, CommandsResponse as i, CheckChangesOptions as it, KeyInput as j, ProcessStartResult as jt, DesktopStatusResponse as k, ProcessLogsResult as kt, PingResponse as l, ExecResult as lt, ExecutionCallbacks as m, FileWatchSSEEvent as mt, getSandbox as n, BucketCredentials as nt, CreateSessionResponse as o, DirectoryBackup as ot, UnexposePortRequest as p, FileStreamEvent as pt, ResponseHandler as q, CreateContextOptions as qt, SandboxClient as r, BucketProvider as rt, DeleteSessionRequest as s, ExecEvent as st, Sandbox as t, BaseExecOptions as tt, UtilityClient as u, ExecutionSession as ut, FileClient as v, LocalMountBucketOptions as vt, CursorPositionResponse as w, Process as wt, ReadFileRequest as x, PortCloseResult as xt, FileOperationRequest as y, LogEvent as yt, CommandClient as z, WaitForLogResult as zt };
+//# sourceMappingURL=sandbox-CwcSm_60.d.ts.map