@cloudflare/sandbox 0.4.18 → 0.5.1

package/dist/index.js

@@ -1,6 +1,20 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 
+//#region ../shared/dist/env.js
+/**
+* Safely extract a string value from an environment object
+*
+* @param env - Environment object with dynamic keys
+* @param key - The environment variable key to access
+* @returns The string value if present and is a string, undefined otherwise
+*/
+function getEnvString(env, key) {
+	const value = env?.[key];
+	return typeof value === "string" ? value : void 0;
+}
+
+//#endregion
 //#region ../shared/dist/git.js
 /**
 * Redact credentials from URLs for secure logging
@@ -225,6 +239,9 @@ var LogLevel;
 //#endregion
 //#region ../shared/dist/logger/logger.js
 /**
+* Logger implementation
+*/
+/**
 * ANSI color codes for terminal output
 */
 const COLORS = {
@@ -344,7 +361,7 @@ var CloudflareLogger = class CloudflareLogger {
 	* 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 { 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}]` : "";
@@ -441,6 +458,39 @@ var TraceContext = class TraceContext {
 //#endregion
 //#region ../shared/dist/logger/index.js
 /**
+* Logger module
+*
+* Provides structured, trace-aware logging with:
+* - AsyncLocalStorage for implicit context propagation
+* - Pretty printing for local development
+* - JSON output for production
+* - Environment auto-detection
+* - Log level configuration
+*
+* Usage:
+*
+* ```typescript
+* // Create a logger at entry point
+* const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc123' });
+*
+* // Store in AsyncLocalStorage for entire request
+* await runWithLogger(logger, async () => {
+*   await handleRequest();
+* });
+*
+* // Retrieve logger anywhere in call stack
+* const logger = getLogger();
+* logger.info('Operation started');
+*
+* // Add operation-specific context
+* const execLogger = logger.child({ operation: 'exec', commandId: 'cmd-456' });
+* await runWithLogger(execLogger, async () => {
+*   // All nested calls automatically get execLogger
+*   await executeCommand();
+* });
+* ```
+*/
+/**
 * Create a no-op logger for testing
 *
 * Returns a logger that implements the Logger interface but does nothing.
@@ -474,25 +524,6 @@ function createNoOpLogger() {
 */
 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().
@@ -600,6 +631,17 @@ function getEnvVar(name) {
 	}
 }
 
+//#endregion
+//#region ../shared/dist/shell-escape.js
+/**
+* Escapes a string for safe use in shell commands using POSIX single-quote escaping.
+* Prevents command injection by wrapping the string in single quotes and escaping
+* any single quotes within the string.
+*/
+function shellEscape(str) {
+	return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
 //#endregion
 //#region ../shared/dist/types.js
 function isExecResult(value) {
@@ -662,6 +704,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 +741,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 +767,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 +1287,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 +1302,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 +1422,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 +2419,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 +2578,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 +2703,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.1";
 
 //#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 +2733,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 +2774,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 +2820,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() {
@@ -2628,6 +3035,64 @@ var Sandbox = class extends Container {
 		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
 	*/
@@ -2696,7 +3161,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 +3482,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 +3607,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 +3746,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