@cloudflare/sandbox 0.4.18 → 0.5.2

package/dist/index.js

@@ -1,625 +1,6 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import { a as createLogger, c as Execution, d as getEnvString, i as shellEscape, l as ResultImpl, n as isProcess, o as createNoOpLogger, r as isProcessStatus, s as TraceContext, t as isExecResult, u as GitLogger } from "./dist-gVyG2H2h.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 
-//#region ../shared/dist/git.js
-/**
-* Redact credentials from URLs for secure logging
-*
-* Replaces any credentials (username:password, tokens, etc.) embedded
-* in URLs with ****** to prevent sensitive data exposure in logs.
-* Works with URLs embedded in text (e.g., "Error: https://token@github.com/repo.git failed")
-*
-* @param text - String that may contain URLs with credentials
-* @returns String with credentials redacted from any URLs
-*/
-function redactCredentials(text) {
-	let result = text;
-	let pos = 0;
-	while (pos < result.length) {
-		const httpPos = result.indexOf("http://", pos);
-		const httpsPos = result.indexOf("https://", pos);
-		let protocolPos = -1;
-		let protocolLen = 0;
-		if (httpPos === -1 && httpsPos === -1) break;
-		if (httpPos !== -1 && (httpsPos === -1 || httpPos < httpsPos)) {
-			protocolPos = httpPos;
-			protocolLen = 7;
-		} else {
-			protocolPos = httpsPos;
-			protocolLen = 8;
-		}
-		const searchStart = protocolPos + protocolLen;
-		const atPos = result.indexOf("@", searchStart);
-		let urlEnd = searchStart;
-		while (urlEnd < result.length) {
-			const char = result[urlEnd];
-			if (/[\s"'`<>,;{}[\]]/.test(char)) break;
-			urlEnd++;
-		}
-		if (atPos !== -1 && atPos < urlEnd) {
-			result = `${result.substring(0, searchStart)}******${result.substring(atPos)}`;
-			pos = searchStart + 6;
-		} else pos = protocolPos + protocolLen;
-	}
-	return result;
-}
-/**
-* Sanitize data by redacting credentials from any strings
-* Recursively processes objects and arrays to ensure credentials are never leaked
-*/
-function sanitizeGitData(data) {
-	if (typeof data === "string") return redactCredentials(data);
-	if (data === null || data === void 0) return data;
-	if (Array.isArray(data)) return data.map((item) => sanitizeGitData(item));
-	if (typeof data === "object") {
-		const result = {};
-		for (const [key, value] of Object.entries(data)) result[key] = sanitizeGitData(value);
-		return result;
-	}
-	return data;
-}
-/**
-* Logger wrapper that automatically sanitizes git credentials
-*/
-var GitLogger = class GitLogger {
-	baseLogger;
-	constructor(baseLogger) {
-		this.baseLogger = baseLogger;
-	}
-	sanitizeContext(context) {
-		return context ? sanitizeGitData(context) : context;
-	}
-	sanitizeError(error) {
-		if (!error) return error;
-		const sanitized = new Error(redactCredentials(error.message));
-		sanitized.name = error.name;
-		if (error.stack) sanitized.stack = redactCredentials(error.stack);
-		const sanitizedRecord = sanitized;
-		const errorRecord = error;
-		for (const key of Object.keys(error)) if (key !== "message" && key !== "stack" && key !== "name") sanitizedRecord[key] = sanitizeGitData(errorRecord[key]);
-		return sanitized;
-	}
-	debug(message, context) {
-		this.baseLogger.debug(message, this.sanitizeContext(context));
-	}
-	info(message, context) {
-		this.baseLogger.info(message, this.sanitizeContext(context));
-	}
-	warn(message, context) {
-		this.baseLogger.warn(message, this.sanitizeContext(context));
-	}
-	error(message, error, context) {
-		this.baseLogger.error(message, this.sanitizeError(error), this.sanitizeContext(context));
-	}
-	child(context) {
-		const sanitized = sanitizeGitData(context);
-		return new GitLogger(this.baseLogger.child(sanitized));
-	}
-};
-
-//#endregion
-//#region ../shared/dist/interpreter-types.js
-var Execution = class {
-	code;
-	context;
-	/**
-	* All results from the execution
-	*/
-	results = [];
-	/**
-	* Accumulated stdout and stderr
-	*/
-	logs = {
-		stdout: [],
-		stderr: []
-	};
-	/**
-	* Execution error if any
-	*/
-	error;
-	/**
-	* Execution count (for interpreter)
-	*/
-	executionCount;
-	constructor(code, context) {
-		this.code = code;
-		this.context = context;
-	}
-	/**
-	* Convert to a plain object for serialization
-	*/
-	toJSON() {
-		return {
-			code: this.code,
-			logs: this.logs,
-			error: this.error,
-			executionCount: this.executionCount,
-			results: this.results.map((result) => ({
-				text: result.text,
-				html: result.html,
-				png: result.png,
-				jpeg: result.jpeg,
-				svg: result.svg,
-				latex: result.latex,
-				markdown: result.markdown,
-				javascript: result.javascript,
-				json: result.json,
-				chart: result.chart,
-				data: result.data
-			}))
-		};
-	}
-};
-var ResultImpl = class {
-	raw;
-	constructor(raw) {
-		this.raw = raw;
-	}
-	get text() {
-		return this.raw.text || this.raw.data?.["text/plain"];
-	}
-	get html() {
-		return this.raw.html || this.raw.data?.["text/html"];
-	}
-	get png() {
-		return this.raw.png || this.raw.data?.["image/png"];
-	}
-	get jpeg() {
-		return this.raw.jpeg || this.raw.data?.["image/jpeg"];
-	}
-	get svg() {
-		return this.raw.svg || this.raw.data?.["image/svg+xml"];
-	}
-	get latex() {
-		return this.raw.latex || this.raw.data?.["text/latex"];
-	}
-	get markdown() {
-		return this.raw.markdown || this.raw.data?.["text/markdown"];
-	}
-	get javascript() {
-		return this.raw.javascript || this.raw.data?.["application/javascript"];
-	}
-	get json() {
-		return this.raw.json || this.raw.data?.["application/json"];
-	}
-	get chart() {
-		return this.raw.chart;
-	}
-	get data() {
-		return this.raw.data;
-	}
-	formats() {
-		const formats = [];
-		if (this.text) formats.push("text");
-		if (this.html) formats.push("html");
-		if (this.png) formats.push("png");
-		if (this.jpeg) formats.push("jpeg");
-		if (this.svg) formats.push("svg");
-		if (this.latex) formats.push("latex");
-		if (this.markdown) formats.push("markdown");
-		if (this.javascript) formats.push("javascript");
-		if (this.json) formats.push("json");
-		if (this.chart) formats.push("chart");
-		return formats;
-	}
-};
-
-//#endregion
-//#region ../shared/dist/logger/types.js
-/**
-* Logger types for Cloudflare Sandbox SDK
-*
-* Provides structured, trace-aware logging across Worker, Durable Object, and Container.
-*/
-/**
-* Log levels (from most to least verbose)
-*/
-var LogLevel;
-(function(LogLevel$1) {
-	LogLevel$1[LogLevel$1["DEBUG"] = 0] = "DEBUG";
-	LogLevel$1[LogLevel$1["INFO"] = 1] = "INFO";
-	LogLevel$1[LogLevel$1["WARN"] = 2] = "WARN";
-	LogLevel$1[LogLevel$1["ERROR"] = 3] = "ERROR";
-})(LogLevel || (LogLevel = {}));
-
-//#endregion
-//#region ../shared/dist/logger/logger.js
-/**
-* ANSI color codes for terminal output
-*/
-const COLORS = {
-	reset: "\x1B[0m",
-	debug: "\x1B[36m",
-	info: "\x1B[32m",
-	warn: "\x1B[33m",
-	error: "\x1B[31m",
-	dim: "\x1B[2m"
-};
-/**
-* CloudflareLogger implements structured logging with support for
-* both JSON output (production) and pretty printing (development).
-*/
-var CloudflareLogger = class CloudflareLogger {
-	baseContext;
-	minLevel;
-	pretty;
-	/**
-	* Create a new CloudflareLogger
-	*
-	* @param baseContext Base context included in all log entries
-	* @param minLevel Minimum log level to output (default: INFO)
-	* @param pretty Enable pretty printing for human-readable output (default: false)
-	*/
-	constructor(baseContext, minLevel = LogLevel.INFO, pretty = false) {
-		this.baseContext = baseContext;
-		this.minLevel = minLevel;
-		this.pretty = pretty;
-	}
-	/**
-	* Log debug-level message
-	*/
-	debug(message, context) {
-		if (this.shouldLog(LogLevel.DEBUG)) {
-			const logData = this.buildLogData("debug", message, context);
-			this.output(console.log, logData);
-		}
-	}
-	/**
-	* Log info-level message
-	*/
-	info(message, context) {
-		if (this.shouldLog(LogLevel.INFO)) {
-			const logData = this.buildLogData("info", message, context);
-			this.output(console.log, logData);
-		}
-	}
-	/**
-	* Log warning-level message
-	*/
-	warn(message, context) {
-		if (this.shouldLog(LogLevel.WARN)) {
-			const logData = this.buildLogData("warn", message, context);
-			this.output(console.warn, logData);
-		}
-	}
-	/**
-	* Log error-level message
-	*/
-	error(message, error, context) {
-		if (this.shouldLog(LogLevel.ERROR)) {
-			const logData = this.buildLogData("error", message, context, error);
-			this.output(console.error, logData);
-		}
-	}
-	/**
-	* Create a child logger with additional context
-	*/
-	child(context) {
-		return new CloudflareLogger({
-			...this.baseContext,
-			...context
-		}, this.minLevel, this.pretty);
-	}
-	/**
-	* Check if a log level should be output
-	*/
-	shouldLog(level) {
-		return level >= this.minLevel;
-	}
-	/**
-	* Build log data object
-	*/
-	buildLogData(level, message, context, error) {
-		const logData = {
-			level,
-			msg: message,
-			...this.baseContext,
-			...context,
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		if (error) logData.error = {
-			message: error.message,
-			stack: error.stack,
-			name: error.name
-		};
-		return logData;
-	}
-	/**
-	* Output log data to console (pretty or JSON)
-	*/
-	output(consoleFn, data) {
-		if (this.pretty) this.outputPretty(consoleFn, data);
-		else this.outputJson(consoleFn, data);
-	}
-	/**
-	* Output as JSON (production)
-	*/
-	outputJson(consoleFn, data) {
-		consoleFn(JSON.stringify(data));
-	}
-	/**
-	* Output as pretty-printed, colored text (development)
-	*
-	* Format: LEVEL [component] message (trace: tr_...) {context}
-	* Example: INFO [sandbox-do] Command started (trace: tr_7f3a9b2c) {commandId: "cmd-123"}
-	*/
-	outputPretty(consoleFn, data) {
-		const { level, msg, timestamp, traceId, component, sandboxId, sessionId, processId, commandId, operation, duration, error,...rest } = data;
-		const levelStr = String(level || "INFO").toUpperCase();
-		const levelColor = this.getLevelColor(levelStr);
-		const componentBadge = component ? `[${component}]` : "";
-		const traceIdShort = traceId ? String(traceId).substring(0, 12) : "";
-		let logLine = `${levelColor}${levelStr.padEnd(5)}${COLORS.reset} ${componentBadge} ${msg}`;
-		if (traceIdShort) logLine += ` ${COLORS.dim}(trace: ${traceIdShort})${COLORS.reset}`;
-		const contextFields = [];
-		if (operation) contextFields.push(`operation: ${operation}`);
-		if (commandId) contextFields.push(`commandId: ${String(commandId).substring(0, 12)}`);
-		if (sandboxId) contextFields.push(`sandboxId: ${sandboxId}`);
-		if (sessionId) contextFields.push(`sessionId: ${String(sessionId).substring(0, 12)}`);
-		if (processId) contextFields.push(`processId: ${processId}`);
-		if (duration !== void 0) contextFields.push(`duration: ${duration}ms`);
-		if (contextFields.length > 0) logLine += ` ${COLORS.dim}{${contextFields.join(", ")}}${COLORS.reset}`;
-		consoleFn(logLine);
-		if (error && typeof error === "object") {
-			const errorObj = error;
-			if (errorObj.message) consoleFn(`  ${COLORS.error}Error: ${errorObj.message}${COLORS.reset}`);
-			if (errorObj.stack) consoleFn(`  ${COLORS.dim}${errorObj.stack}${COLORS.reset}`);
-		}
-		if (Object.keys(rest).length > 0) consoleFn(`  ${COLORS.dim}${JSON.stringify(rest, null, 2)}${COLORS.reset}`);
-	}
-	/**
-	* Get ANSI color code for log level
-	*/
-	getLevelColor(level) {
-		switch (level.toLowerCase()) {
-			case "debug": return COLORS.debug;
-			case "info": return COLORS.info;
-			case "warn": return COLORS.warn;
-			case "error": return COLORS.error;
-			default: return COLORS.reset;
-		}
-	}
-};
-
-//#endregion
-//#region ../shared/dist/logger/trace-context.js
-/**
-* Trace context utilities for request correlation
-*
-* Trace IDs enable correlating logs across distributed components:
-* Worker → Durable Object → Container → back
-*
-* The trace ID is propagated via the X-Trace-Id HTTP header.
-*/
-/**
-* Utility for managing trace context across distributed components
-*/
-var TraceContext = class TraceContext {
-	/**
-	* HTTP header name for trace ID propagation
-	*/
-	static TRACE_HEADER = "X-Trace-Id";
-	/**
-	* Generate a new trace ID
-	*
-	* Format: "tr_" + 16 random hex characters
-	* Example: "tr_7f3a9b2c4e5d6f1a"
-	*
-	* @returns Newly generated trace ID
-	*/
-	static generate() {
-		return `tr_${crypto.randomUUID().replace(/-/g, "").substring(0, 16)}`;
-	}
-	/**
-	* Extract trace ID from HTTP request headers
-	*
-	* @param headers Request headers
-	* @returns Trace ID if present, null otherwise
-	*/
-	static fromHeaders(headers) {
-		return headers.get(TraceContext.TRACE_HEADER);
-	}
-	/**
-	* Create headers object with trace ID for outgoing requests
-	*
-	* @param traceId Trace ID to include
-	* @returns Headers object with X-Trace-Id set
-	*/
-	static toHeaders(traceId) {
-		return { [TraceContext.TRACE_HEADER]: traceId };
-	}
-	/**
-	* Get the header name used for trace ID propagation
-	*
-	* @returns Header name ("X-Trace-Id")
-	*/
-	static getHeaderName() {
-		return TraceContext.TRACE_HEADER;
-	}
-};
-
-//#endregion
-//#region ../shared/dist/logger/index.js
-/**
-* Create a no-op logger for testing
-*
-* Returns a logger that implements the Logger interface but does nothing.
-* Useful for tests that don't need actual logging output.
-*
-* @returns No-op logger instance
-*
-* @example
-* ```typescript
-* // In tests
-* const client = new HttpClient({
-*   baseUrl: 'http://test.com',
-*   logger: createNoOpLogger() // Optional - tests can enable real logging if needed
-* });
-* ```
-*/
-function createNoOpLogger() {
-	return {
-		debug: () => {},
-		info: () => {},
-		warn: () => {},
-		error: () => {},
-		child: () => createNoOpLogger()
-	};
-}
-/**
-* AsyncLocalStorage for logger context
-*
-* Enables implicit logger propagation throughout the call stack without
-* explicit parameter passing. The logger is stored per async context.
-*/
-const loggerStorage = new AsyncLocalStorage();
-/**
-* Get the current logger from AsyncLocalStorage
-*
-* @throws Error if no logger is initialized in the current async context
-* @returns Current logger instance
-*
-* @example
-* ```typescript
-* function someHelperFunction() {
-*   const logger = getLogger(); // Automatically has all context!
-*   logger.info('Helper called');
-* }
-* ```
-*/
-function getLogger() {
-	const logger = loggerStorage.getStore();
-	if (!logger) throw new Error("Logger not initialized in async context. Ensure runWithLogger() is called at the entry point (e.g., fetch handler).");
-	return logger;
-}
-/**
-* Run a function with a logger stored in AsyncLocalStorage
-*
-* The logger is available to all code within the function via getLogger().
-* This is typically called at request entry points (fetch handler) and when
-* creating child loggers with additional context.
-*
-* @param logger Logger instance to store in context
-* @param fn Function to execute with logger context
-* @returns Result of the function
-*
-* @example
-* ```typescript
-* // At request entry point
-* async fetch(request: Request): Promise<Response> {
-*   const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc' });
-*   return runWithLogger(logger, async () => {
-*     return await this.handleRequest(request);
-*   });
-* }
-*
-* // When adding operation context
-* async exec(command: string) {
-*   const logger = getLogger().child({ operation: 'exec', commandId: 'cmd-123' });
-*   return runWithLogger(logger, async () => {
-*     logger.info('Command started');
-*     await this.executeCommand(command); // Nested calls get the child logger
-*     logger.info('Command completed');
-*   });
-* }
-* ```
-*/
-function runWithLogger(logger, fn) {
-	return loggerStorage.run(logger, fn);
-}
-/**
-* Create a new logger instance
-*
-* @param context Base context for the logger. Must include 'component'.
-*                TraceId will be auto-generated if not provided.
-* @returns New logger instance
-*
-* @example
-* ```typescript
-* // In Durable Object
-* const logger = createLogger({
-*   component: 'sandbox-do',
-*   traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
-*   sandboxId: this.id
-* });
-*
-* // In Container
-* const logger = createLogger({
-*   component: 'container',
-*   traceId: TraceContext.fromHeaders(request.headers)!,
-*   sessionId: this.id
-* });
-* ```
-*/
-function createLogger(context) {
-	const minLevel = getLogLevelFromEnv();
-	const pretty = isPrettyPrintEnabled();
-	return new CloudflareLogger({
-		...context,
-		traceId: context.traceId || TraceContext.generate(),
-		component: context.component
-	}, minLevel, pretty);
-}
-/**
-* Get log level from environment variable
-*
-* Checks SANDBOX_LOG_LEVEL env var, falls back to default based on environment.
-* Default: 'debug' for development, 'info' for production
-*/
-function getLogLevelFromEnv() {
-	switch ((getEnvVar("SANDBOX_LOG_LEVEL") || "info").toLowerCase()) {
-		case "debug": return LogLevel.DEBUG;
-		case "info": return LogLevel.INFO;
-		case "warn": return LogLevel.WARN;
-		case "error": return LogLevel.ERROR;
-		default: return LogLevel.INFO;
-	}
-}
-/**
-* Check if pretty printing should be enabled
-*
-* Checks SANDBOX_LOG_FORMAT env var, falls back to auto-detection:
-* - Local development: pretty (colored, human-readable)
-* - Production: json (structured)
-*/
-function isPrettyPrintEnabled() {
-	const format = getEnvVar("SANDBOX_LOG_FORMAT");
-	if (format) return format.toLowerCase() === "pretty";
-	return false;
-}
-/**
-* Get environment variable value
-*
-* Supports both Node.js (process.env) and Bun (Bun.env)
-*/
-function getEnvVar(name) {
-	if (typeof process !== "undefined" && process.env) return process.env[name];
-	if (typeof Bun !== "undefined") {
-		const bunEnv = Bun.env;
-		if (bunEnv) return bunEnv[name];
-	}
-}
-
-//#endregion
-//#region ../shared/dist/types.js
-function isExecResult(value) {
-	return value && typeof value.success === "boolean" && typeof value.exitCode === "number" && typeof value.stdout === "string" && typeof value.stderr === "string";
-}
-function isProcess(value) {
-	return value && typeof value.id === "string" && typeof value.command === "string" && typeof value.status === "string";
-}
-function isProcessStatus(value) {
-	return [
-		"starting",
-		"running",
-		"completed",
-		"failed",
-		"killed",
-		"error"
-	].includes(value);
-}
-
-//#endregion
 //#region ../shared/dist/errors/codes.js
 /**
 * Centralized error code registry
@@ -662,6 +43,10 @@ const ErrorCode = {
 	GIT_CLONE_FAILED: "GIT_CLONE_FAILED",
 	GIT_CHECKOUT_FAILED: "GIT_CHECKOUT_FAILED",
 	GIT_OPERATION_FAILED: "GIT_OPERATION_FAILED",
+	BUCKET_MOUNT_ERROR: "BUCKET_MOUNT_ERROR",
+	S3FS_MOUNT_ERROR: "S3FS_MOUNT_ERROR",
+	MISSING_CREDENTIALS: "MISSING_CREDENTIALS",
+	INVALID_MOUNT_CONFIG: "INVALID_MOUNT_CONFIG",
 	INTERPRETER_NOT_READY: "INTERPRETER_NOT_READY",
 	CONTEXT_NOT_FOUND: "CONTEXT_NOT_FOUND",
 	CODE_EXECUTION_ERROR: "CODE_EXECUTION_ERROR",
@@ -695,6 +80,8 @@ const ERROR_STATUS_MAP = {
 	[ErrorCode.INVALID_JSON_RESPONSE]: 400,
 	[ErrorCode.NAME_TOO_LONG]: 400,
 	[ErrorCode.VALIDATION_FAILED]: 400,
+	[ErrorCode.MISSING_CREDENTIALS]: 400,
+	[ErrorCode.INVALID_MOUNT_CONFIG]: 400,
 	[ErrorCode.GIT_AUTH_FAILED]: 401,
 	[ErrorCode.PERMISSION_DENIED]: 403,
 	[ErrorCode.COMMAND_PERMISSION_DENIED]: 403,
@@ -719,6 +106,8 @@ const ERROR_STATUS_MAP = {
 	[ErrorCode.GIT_CHECKOUT_FAILED]: 500,
 	[ErrorCode.GIT_OPERATION_FAILED]: 500,
 	[ErrorCode.CODE_EXECUTION_ERROR]: 500,
+	[ErrorCode.BUCKET_MOUNT_ERROR]: 500,
+	[ErrorCode.S3FS_MOUNT_ERROR]: 500,
 	[ErrorCode.UNKNOWN_ERROR]: 500,
 	[ErrorCode.INTERNAL_ERROR]: 500
 };
@@ -1237,8 +626,8 @@ function createErrorFromResponse(errorResponse) {
 
 //#endregion
 //#region src/clients/base-client.ts
-const TIMEOUT_MS = 6e4;
-const MIN_TIME_FOR_RETRY_MS = 1e4;
+const TIMEOUT_MS = 12e4;
+const MIN_TIME_FOR_RETRY_MS = 15e3;
 /**
 * Abstract base class providing common HTTP functionality for all domain clients
 */
@@ -1252,31 +641,31 @@ var BaseHttpClient = class {
 		this.baseUrl = this.options.baseUrl;
 	}
 	/**
-	* Core HTTP request method with automatic retry for container provisioning delays
+	* Core HTTP request method with automatic retry for container startup delays
+	* Retries both 503 (provisioning) and 500 (startup failure) errors when they're container-related
 	*/
 	async doFetch(path, options) {
 		const startTime = Date.now();
 		let attempt = 0;
 		while (true) {
 			const response = await this.executeFetch(path, options);
-			if (response.status === 503) {
-				if (await this.isContainerProvisioningError(response)) {
-					const remaining = TIMEOUT_MS - (Date.now() - startTime);
-					if (remaining > MIN_TIME_FOR_RETRY_MS) {
-						const delay = Math.min(2e3 * 2 ** attempt, 16e3);
-						this.logger.info("Container provisioning in progress, retrying", {
-							attempt: attempt + 1,
-							delayMs: delay,
-							remainingSec: Math.floor(remaining / 1e3)
-						});
-						await new Promise((resolve) => setTimeout(resolve, delay));
-						attempt++;
-						continue;
-					} else {
-						this.logger.error("Container failed to provision after multiple attempts", /* @__PURE__ */ new Error(`Failed after ${attempt + 1} attempts over 60s`));
-						return response;
-					}
+			if (await this.isRetryableContainerError(response)) {
+				const elapsed = Date.now() - startTime;
+				const remaining = TIMEOUT_MS - elapsed;
+				if (remaining > MIN_TIME_FOR_RETRY_MS) {
+					const delay = Math.min(3e3 * 2 ** attempt, 3e4);
+					this.logger.info("Container not ready, retrying", {
+						status: response.status,
+						attempt: attempt + 1,
+						delayMs: delay,
+						remainingSec: Math.floor(remaining / 1e3)
+					});
+					await new Promise((resolve) => setTimeout(resolve, delay));
+					attempt++;
+					continue;
 				}
+				this.logger.error("Container failed to become ready", /* @__PURE__ */ new Error(`Failed after ${attempt + 1} attempts over ${Math.floor(elapsed / 1e3)}s`));
+				return response;
 			}
 			return response;
 		}
@@ -1372,14 +761,50 @@ var BaseHttpClient = class {
 		} else this.logger.error(`Error in ${operation}`, error instanceof Error ? error : new Error(String(error)));
 	}
 	/**
-	* Check if 503 response is from container provisioning (retryable)
-	* vs user application (not retryable)
+	* Check if response indicates a retryable container error
+	* Uses fail-safe strategy: only retry known transient errors
+	*
+	* TODO: This relies on string matching error messages, which is brittle.
+	* Ideally, the container API should return structured errors with a
+	* `retryable: boolean` field to avoid coupling to error message format.
+	*
+	* @param response - HTTP response to check
+	* @returns true if error is retryable container error, false otherwise
 	*/
-	async isContainerProvisioningError(response) {
+	async isRetryableContainerError(response) {
+		if (response.status !== 500 && response.status !== 503) return false;
 		try {
-			return (await response.clone().text()).includes("There is no Container instance available");
+			const text = await response.clone().text();
+			const textLower = text.toLowerCase();
+			if ([
+				"no such image",
+				"container already exists",
+				"malformed containerinspect"
+			].some((err) => textLower.includes(err))) {
+				this.logger.debug("Detected permanent error, not retrying", { text });
+				return false;
+			}
+			const shouldRetry = [
+				"no container instance available",
+				"currently provisioning",
+				"container port not found",
+				"connection refused: container port",
+				"the container is not listening",
+				"failed to verify port",
+				"container did not start",
+				"network connection lost",
+				"container suddenly disconnected",
+				"monitor failed to find container",
+				"timed out",
+				"timeout"
+			].some((err) => textLower.includes(err));
+			if (!shouldRetry) this.logger.debug("Unknown error pattern, not retrying", {
+				status: response.status,
+				text: text.substring(0, 200)
+			});
+			return shouldRetry;
 		} catch (error) {
-			this.logger.error("Error checking response body", error instanceof Error ? error : new Error(String(error)));
+			this.logger.error("Error checking if response is retryable", error instanceof Error ? error : new Error(String(error)));
 			return false;
 		}
 	}
@@ -2333,7 +1758,7 @@ async function proxyToSandbox(request, env) {
 		const routeInfo = extractSandboxRoute(url);
 		if (!routeInfo) return null;
 		const { sandboxId, port, path, token } = routeInfo;
-		const sandbox = getSandbox(env.Sandbox, sandboxId);
+		const sandbox = getSandbox(env.Sandbox, sandboxId, { normalizeId: true });
 		if (port !== 3e3) {
 			if (!await sandbox.validatePortToken(port, token)) {
 				logger.warn("Invalid token access blocked", {
@@ -2492,6 +1917,124 @@ function asyncIterableToSSEStream(events, options) {
 	});
 }
 
+//#endregion
+//#region src/storage-mount/errors.ts
+/**
+* Bucket mounting error classes
+*
+* These are SDK-side validation errors that follow the same pattern as SecurityError.
+* They are thrown before any container interaction occurs.
+*/
+/**
+* Base error for bucket mounting operations
+*/
+var BucketMountError = class extends Error {
+	code;
+	constructor(message, code = ErrorCode.BUCKET_MOUNT_ERROR) {
+		super(message);
+		this.name = "BucketMountError";
+		this.code = code;
+	}
+};
+/**
+* Thrown when S3FS mount command fails
+*/
+var S3FSMountError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.S3FS_MOUNT_ERROR);
+		this.name = "S3FSMountError";
+	}
+};
+/**
+* Thrown when no credentials found in environment
+*/
+var MissingCredentialsError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.MISSING_CREDENTIALS);
+		this.name = "MissingCredentialsError";
+	}
+};
+/**
+* Thrown when bucket name, mount path, or options are invalid
+*/
+var InvalidMountConfigError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.INVALID_MOUNT_CONFIG);
+		this.name = "InvalidMountConfigError";
+	}
+};
+
+//#endregion
+//#region src/storage-mount/credential-detection.ts
+/**
+* Detect credentials for bucket mounting from environment variables
+* Priority order:
+* 1. Explicit options.credentials
+* 2. Standard AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
+* 3. Error: no credentials found
+*
+* @param options - Mount options
+* @param envVars - Environment variables
+* @returns Detected credentials
+* @throws MissingCredentialsError if no credentials found
+*/
+function detectCredentials(options, envVars) {
+	if (options.credentials) return options.credentials;
+	const awsAccessKeyId = envVars.AWS_ACCESS_KEY_ID;
+	const awsSecretAccessKey = envVars.AWS_SECRET_ACCESS_KEY;
+	if (awsAccessKeyId && awsSecretAccessKey) return {
+		accessKeyId: awsAccessKeyId,
+		secretAccessKey: awsSecretAccessKey
+	};
+	throw new MissingCredentialsError("No credentials found. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or pass explicit credentials in options.");
+}
+
+//#endregion
+//#region src/storage-mount/provider-detection.ts
+/**
+* Detect provider from endpoint URL using pattern matching
+*/
+function detectProviderFromUrl(endpoint) {
+	try {
+		const hostname = new URL(endpoint).hostname.toLowerCase();
+		if (hostname.endsWith(".r2.cloudflarestorage.com")) return "r2";
+		if (hostname.endsWith(".amazonaws.com") || hostname === "s3.amazonaws.com") return "s3";
+		if (hostname === "storage.googleapis.com") return "gcs";
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Get s3fs flags for a given provider
+*
+* Based on s3fs-fuse wiki recommendations:
+* https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3
+*/
+function getProviderFlags(provider) {
+	if (!provider) return ["use_path_request_style"];
+	switch (provider) {
+		case "r2": return ["nomixupload"];
+		case "s3": return [];
+		case "gcs": return [];
+		default: return ["use_path_request_style"];
+	}
+}
+/**
+* Resolve s3fs options by combining provider defaults with user overrides
+*/
+function resolveS3fsOptions(provider, userOptions) {
+	const providerFlags = getProviderFlags(provider);
+	if (!userOptions || userOptions.length === 0) return providerFlags;
+	const allFlags = [...providerFlags, ...userOptions];
+	const flagMap = /* @__PURE__ */ new Map();
+	for (const flag of allFlags) {
+		const [flagName] = flag.split("=");
+		flagMap.set(flagName, flag);
+	}
+	return Array.from(flagMap.values());
+}
+
 //#endregion
 //#region src/version.ts
 /**
@@ -2499,16 +2042,21 @@ function asyncIterableToSSEStream(events, options) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.4.18";
+const SDK_VERSION = "0.5.2";
 
 //#endregion
 //#region src/sandbox.ts
 function getSandbox(ns, id, options) {
-	const stub = getContainer(ns, id);
-	stub.setSandboxName?.(id);
+	const sanitizedId = sanitizeSandboxId(id);
+	const effectiveId = options?.normalizeId ? sanitizedId.toLowerCase() : sanitizedId;
+	const hasUppercase = /[A-Z]/.test(sanitizedId);
+	if (!options?.normalizeId && hasUppercase) createLogger({ component: "sandbox-do" }).warn(`Sandbox ID "${sanitizedId}" contains uppercase letters, which causes issues with preview URLs (hostnames are case-insensitive). normalizeId will default to true in a future version to prevent this. Use lowercase IDs or pass { normalizeId: true } to prepare.`);
+	const stub = getContainer(ns, effectiveId);
+	stub.setSandboxName?.(effectiveId, options?.normalizeId);
 	if (options?.baseUrl) stub.setBaseUrl(options.baseUrl);
 	if (options?.sleepAfter !== void 0) stub.setSleepAfter(options.sleepAfter);
 	if (options?.keepAlive !== void 0) stub.setKeepAlive(options.keepAlive);
+	if (options?.containerTimeouts) stub.setContainerTimeouts(options.containerTimeouts);
 	return Object.assign(stub, { wsConnect: connect(stub) });
 }
 function connect(stub) {
@@ -2524,18 +2072,35 @@ var Sandbox = class extends Container {
 	client;
 	codeInterpreter;
 	sandboxName = null;
+	normalizeId = false;
 	baseUrl = null;
 	portTokens = /* @__PURE__ */ new Map();
 	defaultSession = null;
 	envVars = {};
 	logger;
 	keepAliveEnabled = false;
+	activeMounts = /* @__PURE__ */ new Map();
+	/**
+	* Default container startup timeouts (conservative for production)
+	* Based on Cloudflare docs: "Containers take several minutes to provision"
+	*/
+	DEFAULT_CONTAINER_TIMEOUTS = {
+		instanceGetTimeoutMS: 3e4,
+		portReadyTimeoutMS: 9e4,
+		waitIntervalMS: 1e3
+	};
+	/**
+	* Active container timeout configuration
+	* Can be set via options, env vars, or defaults
+	*/
+	containerTimeouts = { ...this.DEFAULT_CONTAINER_TIMEOUTS };
 	constructor(ctx, env) {
 		super(ctx, env);
 		const envObj = env;
 		["SANDBOX_LOG_LEVEL", "SANDBOX_LOG_FORMAT"].forEach((key) => {
-			if (envObj?.[key]) this.envVars[key] = envObj[key];
+			if (envObj?.[key]) this.envVars[key] = String(envObj[key]);
 		});
+		this.containerTimeouts = this.getDefaultTimeouts(envObj);
 		this.logger = createLogger({
 			component: "sandbox-do",
 			sandboxId: this.ctx.id.toString()
@@ -2548,16 +2113,24 @@ var Sandbox = class extends Container {
 		this.codeInterpreter = new CodeInterpreter(this);
 		this.ctx.blockConcurrencyWhile(async () => {
 			this.sandboxName = await this.ctx.storage.get("sandboxName") || null;
+			this.normalizeId = await this.ctx.storage.get("normalizeId") || false;
 			this.defaultSession = await this.ctx.storage.get("defaultSession") || null;
 			const storedTokens = await this.ctx.storage.get("portTokens") || {};
 			this.portTokens = /* @__PURE__ */ new Map();
 			for (const [portStr, token] of Object.entries(storedTokens)) this.portTokens.set(parseInt(portStr, 10), token);
+			const storedTimeouts = await this.ctx.storage.get("containerTimeouts");
+			if (storedTimeouts) this.containerTimeouts = {
+				...this.containerTimeouts,
+				...storedTimeouts
+			};
 		});
 	}
-	async setSandboxName(name) {
+	async setSandboxName(name, normalizeId) {
 		if (!this.sandboxName) {
 			this.sandboxName = name;
+			this.normalizeId = normalizeId || false;
 			await this.ctx.storage.put("sandboxName", name);
+			await this.ctx.storage.put("normalizeId", this.normalizeId);
 		}
 	}
 	async setBaseUrl(baseUrl) {
@@ -2586,10 +2159,183 @@ var Sandbox = class extends Container {
 		}
 	}
 	/**
+	* RPC method to configure container startup timeouts
+	*/
+	async setContainerTimeouts(timeouts) {
+		const validated = { ...this.containerTimeouts };
+		if (timeouts.instanceGetTimeoutMS !== void 0) validated.instanceGetTimeoutMS = this.validateTimeout(timeouts.instanceGetTimeoutMS, "instanceGetTimeoutMS", 5e3, 3e5);
+		if (timeouts.portReadyTimeoutMS !== void 0) validated.portReadyTimeoutMS = this.validateTimeout(timeouts.portReadyTimeoutMS, "portReadyTimeoutMS", 1e4, 6e5);
+		if (timeouts.waitIntervalMS !== void 0) validated.waitIntervalMS = this.validateTimeout(timeouts.waitIntervalMS, "waitIntervalMS", 100, 5e3);
+		this.containerTimeouts = validated;
+		await this.ctx.storage.put("containerTimeouts", this.containerTimeouts);
+		this.logger.debug("Container timeouts updated", this.containerTimeouts);
+	}
+	/**
+	* Validate a timeout value is within acceptable range
+	* Throws error if invalid - used for user-provided values
+	*/
+	validateTimeout(value, name, min, max) {
+		if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) throw new Error(`${name} must be a valid finite number, got ${value}`);
+		if (value < min || value > max) throw new Error(`${name} must be between ${min}-${max}ms, got ${value}ms`);
+		return value;
+	}
+	/**
+	* Get default timeouts with env var fallbacks and validation
+	* Precedence: SDK defaults < Env vars < User config
+	*/
+	getDefaultTimeouts(env) {
+		const parseAndValidate = (envVar, name, min, max) => {
+			const defaultValue = this.DEFAULT_CONTAINER_TIMEOUTS[name];
+			if (envVar === void 0) return defaultValue;
+			const parsed = parseInt(envVar, 10);
+			if (Number.isNaN(parsed)) {
+				this.logger.warn(`Invalid ${name}: "${envVar}" is not a number. Using default: ${defaultValue}ms`);
+				return defaultValue;
+			}
+			if (parsed < min || parsed > max) {
+				this.logger.warn(`Invalid ${name}: ${parsed}ms. Must be ${min}-${max}ms. Using default: ${defaultValue}ms`);
+				return defaultValue;
+			}
+			return parsed;
+		};
+		return {
+			instanceGetTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_INSTANCE_TIMEOUT_MS"), "instanceGetTimeoutMS", 5e3, 3e5),
+			portReadyTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_PORT_TIMEOUT_MS"), "portReadyTimeoutMS", 1e4, 6e5),
+			waitIntervalMS: parseAndValidate(getEnvString(env, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
+		};
+	}
+	async mountBucket(bucket, mountPath, options) {
+		this.logger.info(`Mounting bucket ${bucket} to ${mountPath}`);
+		this.validateMountOptions(bucket, mountPath, options);
+		const provider = options.provider || detectProviderFromUrl(options.endpoint);
+		this.logger.debug(`Detected provider: ${provider || "unknown"}`, { explicitProvider: options.provider });
+		const credentials = detectCredentials(options, this.envVars);
+		const passwordFilePath = this.generatePasswordFilePath();
+		this.activeMounts.set(mountPath, {
+			bucket,
+			mountPath,
+			endpoint: options.endpoint,
+			provider,
+			passwordFilePath,
+			mounted: false
+		});
+		try {
+			await this.createPasswordFile(passwordFilePath, bucket, credentials);
+			await this.exec(`mkdir -p ${shellEscape(mountPath)}`);
+			await this.executeS3FSMount(bucket, mountPath, options, provider, passwordFilePath);
+			this.activeMounts.set(mountPath, {
+				bucket,
+				mountPath,
+				endpoint: options.endpoint,
+				provider,
+				passwordFilePath,
+				mounted: true
+			});
+			this.logger.info(`Successfully mounted bucket ${bucket} to ${mountPath}`);
+		} catch (error) {
+			await this.deletePasswordFile(passwordFilePath);
+			this.activeMounts.delete(mountPath);
+			throw error;
+		}
+	}
+	/**
+	* Manually unmount a bucket filesystem
+	*
+	* @param mountPath - Absolute path where the bucket is mounted
+	* @throws InvalidMountConfigError if mount path doesn't exist or isn't mounted
+	*/
+	async unmountBucket(mountPath) {
+		this.logger.info(`Unmounting bucket from ${mountPath}`);
+		const mountInfo = this.activeMounts.get(mountPath);
+		if (!mountInfo) throw new InvalidMountConfigError(`No active mount found at path: ${mountPath}`);
+		try {
+			await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
+			mountInfo.mounted = false;
+			this.activeMounts.delete(mountPath);
+		} finally {
+			await this.deletePasswordFile(mountInfo.passwordFilePath);
+		}
+		this.logger.info(`Successfully unmounted bucket from ${mountPath}`);
+	}
+	/**
+	* Validate mount options
+	*/
+	validateMountOptions(bucket, mountPath, options) {
+		if (!options.endpoint) throw new InvalidMountConfigError("Endpoint is required. Provide the full S3-compatible endpoint URL.");
+		try {
+			new URL(options.endpoint);
+		} catch (error) {
+			throw new InvalidMountConfigError(`Invalid endpoint URL: "${options.endpoint}". Must be a valid HTTP(S) URL.`);
+		}
+		if (!/^[a-z0-9]([a-z0-9.-]{0,61}[a-z0-9])?$/.test(bucket)) throw new InvalidMountConfigError(`Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, dots, or hyphens, and cannot start/end with dots or hyphens.`);
+		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
+		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
+	}
+	/**
+	* Generate unique password file path for s3fs credentials
+	*/
+	generatePasswordFilePath() {
+		return `/tmp/.passwd-s3fs-${crypto.randomUUID()}`;
+	}
+	/**
+	* Create password file with s3fs credentials
+	* Format: bucket:accessKeyId:secretAccessKey
+	*/
+	async createPasswordFile(passwordFilePath, bucket, credentials) {
+		const content = `${bucket}:${credentials.accessKeyId}:${credentials.secretAccessKey}`;
+		await this.writeFile(passwordFilePath, content);
+		await this.exec(`chmod 0600 ${shellEscape(passwordFilePath)}`);
+		this.logger.debug(`Created password file: ${passwordFilePath}`);
+	}
+	/**
+	* Delete password file
+	*/
+	async deletePasswordFile(passwordFilePath) {
+		try {
+			await this.exec(`rm -f ${shellEscape(passwordFilePath)}`);
+			this.logger.debug(`Deleted password file: ${passwordFilePath}`);
+		} catch (error) {
+			this.logger.warn(`Failed to delete password file ${passwordFilePath}`, { error: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	/**
+	* Execute S3FS mount command
+	*/
+	async executeS3FSMount(bucket, mountPath, options, provider, passwordFilePath) {
+		const resolvedOptions = resolveS3fsOptions(provider, options.s3fsOptions);
+		const s3fsArgs = [];
+		s3fsArgs.push(`passwd_file=${passwordFilePath}`);
+		s3fsArgs.push(...resolvedOptions);
+		if (options.readOnly) s3fsArgs.push("ro");
+		s3fsArgs.push(`url=${options.endpoint}`);
+		const optionsStr = shellEscape(s3fsArgs.join(","));
+		const mountCmd = `s3fs ${shellEscape(bucket)} ${shellEscape(mountPath)} -o ${optionsStr}`;
+		this.logger.debug("Executing s3fs mount", {
+			bucket,
+			mountPath,
+			provider,
+			resolvedOptions
+		});
+		const result = await this.exec(mountCmd);
+		if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
+		this.logger.debug("Mount command executed successfully");
+	}
+	/**
 	* Cleanup and destroy the sandbox container
 	*/
 	async destroy() {
 		this.logger.info("Destroying sandbox container");
+		for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
+			if (mountInfo.mounted) try {
+				this.logger.info(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
+				await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
+				mountInfo.mounted = false;
+			} catch (error) {
+				const errorMsg = error instanceof Error ? error.message : String(error);
+				this.logger.warn(`Failed to unmount bucket ${mountInfo.bucket} from ${mountPath}: ${errorMsg}`);
+			}
+			await this.deletePasswordFile(mountInfo.passwordFilePath);
+		}
 		await super.destroy();
 	}
 	onStart() {
@@ -2621,13 +2367,75 @@ var Sandbox = class extends Container {
 			this.logger.debug("Version compatibility check encountered an error", { error: error instanceof Error ? error.message : String(error) });
 		}
 	}
-	onStop() {
+	async onStop() {
 		this.logger.debug("Sandbox stopped");
+		this.portTokens.clear();
+		this.defaultSession = null;
+		this.activeMounts.clear();
+		await Promise.all([this.ctx.storage.delete("portTokens"), this.ctx.storage.delete("defaultSession")]);
 	}
 	onError(error) {
 		this.logger.error("Sandbox error", error instanceof Error ? error : new Error(String(error)));
 	}
 	/**
+	* Override Container.containerFetch to use production-friendly timeouts
+	* Automatically starts container with longer timeouts if not running
+	*/
+	async containerFetch(requestOrUrl, portOrInit, portParam) {
+		const { request, port } = this.parseContainerFetchArgs(requestOrUrl, portOrInit, portParam);
+		if ((await this.getState()).status !== "healthy") try {
+			this.logger.debug("Starting container with configured timeouts", {
+				instanceTimeout: this.containerTimeouts.instanceGetTimeoutMS,
+				portTimeout: this.containerTimeouts.portReadyTimeoutMS
+			});
+			await this.startAndWaitForPorts({
+				ports: port,
+				cancellationOptions: {
+					instanceGetTimeoutMS: this.containerTimeouts.instanceGetTimeoutMS,
+					portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
+					waitInterval: this.containerTimeouts.waitIntervalMS,
+					abort: request.signal
+				}
+			});
+		} catch (e) {
+			if (this.isNoInstanceError(e)) return new Response("Container is currently provisioning. This can take several minutes on first deployment. Please retry in a moment.", {
+				status: 503,
+				headers: { "Retry-After": "10" }
+			});
+			this.logger.error("Container startup failed", e instanceof Error ? e : new Error(String(e)));
+			return new Response(`Failed to start container: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
+		}
+		return await super.containerFetch(requestOrUrl, portOrInit, portParam);
+	}
+	/**
+	* Helper: Check if error is "no container instance available"
+	*/
+	isNoInstanceError(error) {
+		return error instanceof Error && error.message.toLowerCase().includes("no container instance");
+	}
+	/**
+	* Helper: Parse containerFetch arguments (supports multiple signatures)
+	*/
+	parseContainerFetchArgs(requestOrUrl, portOrInit, portParam) {
+		let request;
+		let port;
+		if (requestOrUrl instanceof Request) {
+			request = requestOrUrl;
+			port = typeof portOrInit === "number" ? portOrInit : void 0;
+		} else {
+			const url = typeof requestOrUrl === "string" ? requestOrUrl : requestOrUrl.toString();
+			const init = typeof portOrInit === "number" ? {} : portOrInit || {};
+			port = typeof portOrInit === "number" ? portOrInit : typeof portParam === "number" ? portParam : void 0;
+			request = new Request(url, init);
+		}
+		port ??= this.defaultPort;
+		if (port === void 0) throw new Error("No port specified for container fetch");
+		return {
+			request,
+			port
+		};
+	}
+	/**
 	* Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
 	* When keepAlive is disabled, calls parent implementation which stops the container
 	*/
@@ -2644,28 +2452,26 @@ var Sandbox = class extends Container {
 			traceId,
 			operation: "fetch"
 		});
-		return await runWithLogger(requestLogger, async () => {
-			const url = new URL(request.url);
-			if (!this.sandboxName && request.headers.has("X-Sandbox-Name")) {
-				const name = request.headers.get("X-Sandbox-Name");
-				this.sandboxName = name;
-				await this.ctx.storage.put("sandboxName", name);
-			}
-			const upgradeHeader = request.headers.get("Upgrade");
-			const connectionHeader = request.headers.get("Connection");
-			if (upgradeHeader?.toLowerCase() === "websocket" && connectionHeader?.toLowerCase().includes("upgrade")) try {
-				requestLogger.debug("WebSocket upgrade requested", {
-					path: url.pathname,
-					port: this.determinePort(url)
-				});
-				return await super.fetch(request);
-			} catch (error) {
-				requestLogger.error("WebSocket connection failed", error instanceof Error ? error : new Error(String(error)), { path: url.pathname });
-				throw error;
-			}
-			const port = this.determinePort(url);
-			return await this.containerFetch(request, port);
-		});
+		const url = new URL(request.url);
+		if (!this.sandboxName && request.headers.has("X-Sandbox-Name")) {
+			const name = request.headers.get("X-Sandbox-Name");
+			this.sandboxName = name;
+			await this.ctx.storage.put("sandboxName", name);
+		}
+		const upgradeHeader = request.headers.get("Upgrade");
+		const connectionHeader = request.headers.get("Connection");
+		if (upgradeHeader?.toLowerCase() === "websocket" && connectionHeader?.toLowerCase().includes("upgrade")) try {
+			requestLogger.debug("WebSocket upgrade requested", {
+				path: url.pathname,
+				port: this.determinePort(url)
+			});
+			return await super.fetch(request);
+		} catch (error) {
+			requestLogger.error("WebSocket connection failed", error instanceof Error ? error : new Error(String(error)), { path: url.pathname });
+			throw error;
+		}
+		const port = this.determinePort(url);
+		return await this.containerFetch(request, port);
 	}
 	wsConnect(request, port) {
 		throw new Error("Not implemented here to avoid RPC serialization issues");
@@ -2696,7 +2502,7 @@ var Sandbox = class extends Container {
 				await this.ctx.storage.put("defaultSession", sessionId);
 				this.logger.debug("Default session initialized", { sessionId });
 			} catch (error) {
-				if (error?.message?.includes("already exists")) {
+				if (error instanceof Error && error.message.includes("already exists")) {
 					this.logger.debug("Reusing existing session after reload", { sessionId });
 					this.defaultSession = sessionId;
 					await this.ctx.storage.put("defaultSession", sessionId);
@@ -3017,7 +2823,10 @@ var Sandbox = class extends Container {
 	}
 	constructPreviewUrl(port, sandboxId, hostname, token) {
 		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
-		const sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+		const effectiveId = this.sandboxName || sandboxId;
+		const hasUppercase = /[A-Z]/.test(effectiveId);
+		if (!this.normalizeId && hasUppercase) throw new SecurityError(`Preview URLs require lowercase sandbox IDs. Your ID "${effectiveId}" contains uppercase letters.\n\nTo fix this:\n1. Create a new sandbox with: getSandbox(ns, "${effectiveId}", { normalizeId: true })\n2. This will create a sandbox with ID: "${effectiveId.toLowerCase()}"\n\nNote: Due to DNS case-insensitivity, IDs with uppercase letters cannot be used with preview URLs.`);
+		const sanitizedSandboxId = sanitizeSandboxId(sandboxId).toLowerCase();
 		if (isLocalhostPattern(hostname)) {
 			const [host, portStr] = hostname.split(":");
 			const mainPort = portStr || "80";
@@ -3139,7 +2948,9 @@ var Sandbox = class extends Container {
 			},
 			runCodeStream: (code, options) => this.codeInterpreter.runCodeStream(code, options),
 			listCodeContexts: () => this.codeInterpreter.listCodeContexts(),
-			deleteCodeContext: (contextId) => this.codeInterpreter.deleteCodeContext(contextId)
+			deleteCodeContext: (contextId) => this.codeInterpreter.deleteCodeContext(contextId),
+			mountBucket: (bucket, mountPath, options) => this.mountBucket(bucket, mountPath, options),
+			unmountBucket: (mountPath) => this.unmountBucket(mountPath)
 		};
 	}
 	async createCodeContext(options) {
@@ -3276,5 +3087,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { CodeInterpreter, CommandClient, Execution, FileClient, GitClient, GitLogger, LogLevel as LogLevelEnum, PortClient, ProcessClient, ResultImpl, Sandbox, SandboxClient, TraceContext, UtilityClient, asyncIterableToSSEStream, collectFile, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, redactCredentials, responseToAsyncIterable, runWithLogger, sanitizeGitData, streamFile };
+export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map