@cloudflare/sandbox 0.10.0 → 0.10.2

package/dist/{sandbox-C-AzrX_L.d.ts → sandbox-KdzTTnWq.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 {
@@ -859,6 +875,15 @@ interface WriteFileResult {
   timestamp: string;
   exitCode?: number;
 }
+/**
+ * Valid `encoding` values accepted by `readFile` / `writeFile` options.
+ *
+ * - `'utf-8'` / `'utf8'` — treat content as text.
+ * - `'base64'` — treat content as base64-encoded binary.
+ * - `'none'` — RPC-only streaming variant of `readFile`, returns a
+ *   `ReadableStream<Uint8Array>` of raw bytes (see `ReadFileStreamResult`).
+ */
+type FileEncoding = 'utf-8' | 'utf8' | 'base64' | 'none';
 interface ReadFileResult {
   success: boolean;
   path: string;
@@ -882,6 +907,21 @@ interface ReadFileResult {
    */
   size?: number;
 }
+/**
+ * Result of `readFile()` with `encoding: 'none'` on the RPC transport.
+ *
+ * `content` is a raw binary `ReadableStream<Uint8Array>` delivered directly
+ * over the capnp channel — no base64 encoding, no SSE framing, no buffering.
+ * Only supported on the `rpc` transport; HTTP/WebSocket transports throw.
+ */
+interface ReadFileStreamResult {
+  success: true;
+  path: string;
+  content: ReadableStream<Uint8Array>;
+  size: number;
+  mimeType: string;
+  timestamp: string;
+}
 interface DeleteFileResult {
   success: boolean;
   path: string;
@@ -1172,8 +1212,11 @@ interface ExecutionSession {
   writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
     encoding?: string;
   }): Promise<WriteFileResult>;
+  readFile(path: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
   readFile(path: string, options?: {
-    encoding?: string;
+    encoding?: Exclude<FileEncoding, 'none'>;
   }): Promise<ReadFileResult>;
   readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
   watch(path: string, options?: Omit<WatchOptions, 'sessionId'>): Promise<ReadableStream<Uint8Array>>;
@@ -1365,9 +1408,36 @@ 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>;
@@ -1388,8 +1458,11 @@ interface ISandbox {
   writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
     encoding?: string;
   }): Promise<WriteFileResult>;
+  readFile(path: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
   readFile(path: string, options?: {
-    encoding?: string;
+    encoding?: Exclude<FileEncoding, 'none'>;
   }): Promise<ReadFileResult>;
   readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
   watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
@@ -1571,8 +1644,11 @@ interface SandboxCommandsAPI {
   }): Promise<ReadableStream<Uint8Array>>;
 }
 interface SandboxFilesAPI {
+  readFile(path: string, sessionId: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
   readFile(path: string, sessionId: string, options?: {
-    encoding?: string;
+    encoding?: Exclude<FileEncoding, 'none'>;
   }): Promise<ReadFileResult>;
   readFileStream(path: string, sessionId: string): Promise<ReadableStream<Uint8Array>>;
   writeFile(path: string, content: string, sessionId: string, options?: {
@@ -1681,8 +1757,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;
@@ -1704,18 +1792,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
 /**
@@ -1922,7 +2039,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
@@ -1957,7 +2074,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
@@ -2085,16 +2202,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.
    */
@@ -2198,11 +2311,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
@@ -2238,7 +2347,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
@@ -2259,13 +2368,21 @@ declare class FileClient extends BaseHttpClient {
     encoding?: string;
   }): Promise<WriteFileResult>;
   /**
-   * Read content from a file
+   * Read content from a file.
+   *
    * @param path - File path to read from
    * @param sessionId - The session ID for this operation
    * @param options - Optional settings (encoding)
+   *
+   * When `encoding` is `'none'`, returns a `ReadFileStreamResult` whose
+   * `content` is a raw `ReadableStream<Uint8Array>`. This variant only works
+   * on the `rpc` transport; HTTP and WebSocket transports throw at runtime.
    */
+  readFile(path: string, sessionId: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
   readFile(path: string, sessionId: string, options?: {
-    encoding?: string;
+    encoding?: Exclude<FileEncoding, 'none'>;
   }): Promise<ReadFileResult>;
   /**
    * Stream a file using Server-Sent Events
@@ -2307,6 +2424,16 @@ declare class FileClient extends BaseHttpClient {
    * @param sessionId - The session ID for this operation
    */
   exists(path: string, sessionId: string): Promise<FileExistsResult>;
+  /**
+   * Write a file via a raw binary stream over the RPC transport.
+   * Throws on HTTP and WebSocket transports — use writeFile() with a string instead.
+   */
+  writeFileStream(_path: string, _content: ReadableStream<Uint8Array>, _sessionId: string): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  }>;
 }
 //#endregion
 //#region src/clients/git-client.d.ts
@@ -2325,7 +2452,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);
   /**
@@ -2351,7 +2478,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>;
@@ -2383,7 +2510,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
@@ -2414,7 +2541,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
@@ -2511,7 +2638,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
    */
@@ -2535,6 +2662,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
@@ -2545,7 +2675,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.
    */
@@ -2589,6 +2719,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);
   /**
@@ -2607,19 +2744,6 @@ declare class SandboxClient {
    * Check if WebSocket is connected (only relevant in WebSocket mode)
    */
   isWebSocketConnected(): boolean;
-  /**
-   * Stream a file directly to the container over a binary RPC channel.
-   *
-   * Requires the container-control path (`transport: 'rpc'`). Calling this
-   * method with the HTTP or WebSocket route transports throws an error because
-   * those transports do not support binary streaming.
-   */
-  writeFileStream(_path: string, _content: ReadableStream<Uint8Array>, _sessionId: string): Promise<{
-    success: boolean;
-    path: string;
-    bytesWritten: number;
-    timestamp: string;
-  }>;
   /**
    * Connect WebSocket transport (no-op in HTTP mode)
    * Called automatically on first request, but can be called explicitly
@@ -2648,6 +2772,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
@@ -2704,13 +2847,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.
@@ -2749,6 +2885,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
@@ -2760,12 +2897,13 @@ declare class ContainerControlClient {
   isWebSocketConnected(): boolean;
   connect(): Promise<void>;
   disconnect(): void;
-  writeFileStream(path: string, stream: ReadableStream<Uint8Array>, sessionId: string): Promise<{
-    success: boolean;
-    path: string;
-    bytesWritten: number;
-    timestamp: string;
-  }>;
+}
+//#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
@@ -2786,6 +2924,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;
@@ -2855,9 +2996,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.
    *
@@ -2927,6 +3075,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
    */
@@ -2939,7 +3094,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;
   /**
@@ -2959,6 +3118,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
@@ -3184,8 +3344,22 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   deleteFile(path: string, sessionId?: string): Promise<DeleteFileResult>;
   renameFile(oldPath: string, newPath: string, sessionId?: string): Promise<RenameFileResult>;
   moveFile(sourcePath: string, destinationPath: string, sessionId?: string): Promise<MoveFileResult>;
+  /**
+   * Read a file from the sandbox.
+   *
+   * @param encoding - How to encode the returned content:
+   *   - `undefined` (default): auto-detect from MIME type (text → UTF-8 string, binary → base64 string)
+   *   - `'utf-8'` / `'utf8'`: always return as UTF-8 string
+   *   - `'base64'`: always return as base64-encoded string
+   *   - `'none'`: return a result whose `content` is a raw binary `ReadableStream<Uint8Array>`
+   *              with no encoding overhead. **Requires `SANDBOX_TRANSPORT=rpc`.** Throws on HTTP/WebSocket transports.
+   */
+  readFile(path: string, options: {
+    encoding: 'none';
+    sessionId?: string;
+  }): Promise<ReadFileStreamResult>;
   readFile(path: string, options?: {
-    encoding?: string;
+    encoding?: Exclude<FileEncoding, 'none'>;
     sessionId?: string;
   }): Promise<ReadFileResult>;
   /**
@@ -3289,6 +3463,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;
@@ -3481,7 +3682,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-C-AzrX_L.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-KdzTTnWq.d.ts.map