@cloudflare/sandbox 0.7.16 → 0.7.18

package/dist/index.js

@@ -2,6 +2,7 @@ import { _ as filterEnvVars, a as isExecResult, c as parseSSEFrames, d as create
 import { t as ErrorCode } from "./errors-CaSfB5Bm.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
+import path from "node:path/posix";
 
 //#region src/errors/classes.ts
 /**
@@ -742,11 +743,11 @@ var BaseTransport = class {
 	* This is the primary entry point for making requests. It wraps the
 	* transport-specific doFetch() with retry logic for container startup.
 	*/
-	async fetch(path, options) {
+	async fetch(path$1, options) {
 		const startTime = Date.now();
 		let attempt = 0;
 		while (true) {
-			const response = await this.doFetch(path, options);
+			const response = await this.doFetch(path$1, options);
 			if (response.status === 503) {
 				const elapsed = Date.now() - startTime;
 				const remaining = this.retryTimeoutMs - elapsed;
@@ -798,13 +799,13 @@ var HttpTransport = class extends BaseTransport {
 	isConnected() {
 		return true;
 	}
-	async doFetch(path, options) {
-		const url = this.buildUrl(path);
+	async doFetch(path$1, options) {
+		const url = this.buildUrl(path$1);
 		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
 		return globalThis.fetch(url, options);
 	}
-	async fetchStream(path, body, method = "POST") {
-		const url = this.buildUrl(path);
+	async fetchStream(path$1, body, method = "POST") {
+		const url = this.buildUrl(path$1);
 		const options = this.buildStreamOptions(body, method);
 		let response;
 		if (this.config.stub) response = await this.config.stub.containerFetch(url, options, this.config.port);
@@ -816,9 +817,9 @@ var HttpTransport = class extends BaseTransport {
 		if (!response.body) throw new Error("No response body for streaming");
 		return response.body;
 	}
-	buildUrl(path) {
-		if (this.config.stub) return `http://localhost:${this.config.port}${path}`;
-		return `${this.baseUrl}${path}`;
+	buildUrl(path$1) {
+		if (this.config.stub) return `http://localhost:${this.config.port}${path$1}`;
+		return `${this.baseUrl}${path$1}`;
 	}
 	buildStreamOptions(body, method) {
 		return {
@@ -877,9 +878,8 @@ var WebSocketTransport = class extends BaseTransport {
 		this.connectPromise = this.doConnect();
 		try {
 			await this.connectPromise;
-		} catch (error) {
+		} finally {
 			this.connectPromise = null;
-			throw error;
 		}
 	}
 	/**
@@ -892,11 +892,11 @@ var WebSocketTransport = class extends BaseTransport {
 	* Transport-specific fetch implementation
 	* Converts WebSocket response to standard Response object.
 	*/
-	async doFetch(path, options) {
+	async doFetch(path$1, options) {
 		await this.connect();
 		const method = options?.method || "GET";
 		const body = this.parseBody(options?.body);
-		const result = await this.request(method, path, body);
+		const result = await this.request(method, path$1, body);
 		return new Response(JSON.stringify(result.body), {
 			status: result.status,
 			headers: { "Content-Type": "application/json" }
@@ -905,8 +905,8 @@ var WebSocketTransport = class extends BaseTransport {
 	/**
 	* Streaming fetch implementation
 	*/
-	async fetchStream(path, body, method = "POST") {
-		return this.requestStream(method, path, body);
+	async fetchStream(path$1, body, method = "POST") {
+		return this.requestStream(method, path$1, body);
 	}
 	/**
 	* Parse request body from RequestInit
@@ -1009,21 +1009,21 @@ var WebSocketTransport = class extends BaseTransport {
 	/**
 	* Send a request and wait for response
 	*/
-	async request(method, path, body) {
+	async request(method, path$1, body) {
 		await this.connect();
 		const id = generateRequestId();
 		const request = {
 			type: "request",
 			id,
 			method,
-			path,
+			path: path$1,
 			body
 		};
 		return new Promise((resolve, reject) => {
 			const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 			const timeoutId = setTimeout(() => {
 				this.pendingRequests.delete(id);
-				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path}`));
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path$1}`));
 			}, timeoutMs);
 			this.pendingRequests.set(id, {
 				resolve: (response) => {
@@ -1065,14 +1065,14 @@ var WebSocketTransport = class extends BaseTransport {
 	* long-running streams (e.g. execStream from an agent) stay alive as long
 	* as data is flowing. The timer resets on every chunk or response message.
 	*/
-	async requestStream(method, path, body) {
+	async requestStream(method, path$1, body) {
 		await this.connect();
 		const id = generateRequestId();
 		const request = {
 			type: "request",
 			id,
 			method,
-			path,
+			path: path$1,
 			body
 		};
 		const idleTimeoutMs = this.config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
@@ -1082,7 +1082,7 @@ var WebSocketTransport = class extends BaseTransport {
 			const createIdleTimeout = () => {
 				return setTimeout(() => {
 					this.pendingRequests.delete(id);
-					const error = /* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms: ${method} ${path}`);
+					const error = /* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms: ${method} ${path$1}`);
 					if (firstMessageReceived) try {
 						streamController?.error(error);
 					} catch {}
@@ -1293,6 +1293,7 @@ var WebSocketTransport = class extends BaseTransport {
 	handleClose(event) {
 		this.state = "disconnected";
 		this.ws = null;
+		this.connectPromise = null;
 		const closeError = /* @__PURE__ */ new Error(`WebSocket closed: ${event.code} ${event.reason || "No reason"}`);
 		for (const [, pending] of this.pendingRequests) {
 			if (pending.timeoutId) clearTimeout(pending.timeoutId);
@@ -1396,8 +1397,8 @@ var BaseHttpClient = class {
 	/**
 	* Core fetch method - delegates to Transport which handles retry logic
 	*/
-	async doFetch(path, options) {
-		return this.transport.fetch(path, options);
+	async doFetch(path$1, options) {
+		return this.transport.fetch(path$1, options);
 	}
 	/**
 	* Make a POST request with JSON body
@@ -1480,14 +1481,14 @@ var BaseHttpClient = class {
 	* @param body - Optional request body (for POST requests)
 	* @param method - HTTP method (default: POST, use GET for process logs)
 	*/
-	async doStreamFetch(path, body, method = "POST") {
+	async doStreamFetch(path$1, body, method = "POST") {
 		if (this.transport.getMode() === "websocket") try {
-			return await this.transport.fetchStream(path, body, method);
+			return await this.transport.fetchStream(path$1, body, method);
 		} catch (error) {
-			this.logError(`stream ${method} ${path}`, error);
+			this.logError(`stream ${method} ${path$1}`, error);
 			throw error;
 		}
-		const response = await this.doFetch(path, {
+		const response = await this.doFetch(path$1, {
 			method,
 			headers: { "Content-Type": "application/json" },
 			body: body && method === "POST" ? JSON.stringify(body) : void 0
@@ -1531,11 +1532,13 @@ var BackupClient = class extends BaseHttpClient {
 	* @param archivePath - Where the container should write the archive
 	* @param sessionId - Session context
 	*/
-	async createArchive(dir, archivePath, sessionId) {
+	async createArchive(dir, archivePath, sessionId, gitignore = false, excludes = []) {
 		try {
 			const data = {
 				dir,
 				archivePath,
+				gitignore,
+				excludes,
 				sessionId
 			};
 			const response = await this.post("/api/backup/create", data);
@@ -2003,15 +2006,15 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	* @param options - Optional settings (recursive)
 	*/
-	async mkdir(path, sessionId, options) {
+	async mkdir(path$1, sessionId, options) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId,
 				recursive: options?.recursive ?? false
 			};
 			const response = await this.post("/api/mkdir", data);
-			this.logSuccess("Directory created", `${path} (recursive: ${data.recursive})`);
+			this.logSuccess("Directory created", `${path$1} (recursive: ${data.recursive})`);
 			return response;
 		} catch (error) {
 			this.logError("mkdir", error);
@@ -2025,16 +2028,16 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	* @param options - Optional settings (encoding)
 	*/
-	async writeFile(path, content, sessionId, options) {
+	async writeFile(path$1, content, sessionId, options) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				content,
 				sessionId,
 				encoding: options?.encoding
 			};
 			const response = await this.post("/api/write", data);
-			this.logSuccess("File written", `${path} (${content.length} chars)`);
+			this.logSuccess("File written", `${path$1} (${content.length} chars)`);
 			return response;
 		} catch (error) {
 			this.logError("writeFile", error);
@@ -2047,15 +2050,15 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	* @param options - Optional settings (encoding)
 	*/
-	async readFile(path, sessionId, options) {
+	async readFile(path$1, sessionId, options) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId,
 				encoding: options?.encoding
 			};
 			const response = await this.post("/api/read", data);
-			this.logSuccess("File read", `${path} (${response.content.length} chars)`);
+			this.logSuccess("File read", `${path$1} (${response.content.length} chars)`);
 			return response;
 		} catch (error) {
 			this.logError("readFile", error);
@@ -2068,14 +2071,14 @@ var FileClient = class extends BaseHttpClient {
 	* @param path - File path to stream
 	* @param sessionId - The session ID for this operation
 	*/
-	async readFileStream(path, sessionId) {
+	async readFileStream(path$1, sessionId) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId
 			};
 			const stream = await this.doStreamFetch("/api/read/stream", data);
-			this.logSuccess("File stream started", path);
+			this.logSuccess("File stream started", path$1);
 			return stream;
 		} catch (error) {
 			this.logError("readFileStream", error);
@@ -2087,14 +2090,14 @@ var FileClient = class extends BaseHttpClient {
 	* @param path - File path to delete
 	* @param sessionId - The session ID for this operation
 	*/
-	async deleteFile(path, sessionId) {
+	async deleteFile(path$1, sessionId) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId
 			};
 			const response = await this.post("/api/delete", data);
-			this.logSuccess("File deleted", path);
+			this.logSuccess("File deleted", path$1);
 			return response;
 		} catch (error) {
 			this.logError("deleteFile", error);
@@ -2107,15 +2110,15 @@ var FileClient = class extends BaseHttpClient {
 	* @param newPath - New file path
 	* @param sessionId - The session ID for this operation
 	*/
-	async renameFile(path, newPath, sessionId) {
+	async renameFile(path$1, newPath, sessionId) {
 		try {
 			const data = {
-				oldPath: path,
+				oldPath: path$1,
 				newPath,
 				sessionId
 			};
 			const response = await this.post("/api/rename", data);
-			this.logSuccess("File renamed", `${path} -> ${newPath}`);
+			this.logSuccess("File renamed", `${path$1} -> ${newPath}`);
 			return response;
 		} catch (error) {
 			this.logError("renameFile", error);
@@ -2128,15 +2131,15 @@ var FileClient = class extends BaseHttpClient {
 	* @param newPath - Destination file path
 	* @param sessionId - The session ID for this operation
 	*/
-	async moveFile(path, newPath, sessionId) {
+	async moveFile(path$1, newPath, sessionId) {
 		try {
 			const data = {
-				sourcePath: path,
+				sourcePath: path$1,
 				destinationPath: newPath,
 				sessionId
 			};
 			const response = await this.post("/api/move", data);
-			this.logSuccess("File moved", `${path} -> ${newPath}`);
+			this.logSuccess("File moved", `${path$1} -> ${newPath}`);
 			return response;
 		} catch (error) {
 			this.logError("moveFile", error);
@@ -2149,15 +2152,15 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	* @param options - Optional settings (recursive, includeHidden)
 	*/
-	async listFiles(path, sessionId, options) {
+	async listFiles(path$1, sessionId, options) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId,
 				options: options || {}
 			};
 			const response = await this.post("/api/list-files", data);
-			this.logSuccess("Files listed", `${path} (${response.count} files)`);
+			this.logSuccess("Files listed", `${path$1} (${response.count} files)`);
 			return response;
 		} catch (error) {
 			this.logError("listFiles", error);
@@ -2169,14 +2172,14 @@ var FileClient = class extends BaseHttpClient {
 	* @param path - Path to check
 	* @param sessionId - The session ID for this operation
 	*/
-	async exists(path, sessionId) {
+	async exists(path$1, sessionId) {
 		try {
 			const data = {
-				path,
+				path: path$1,
 				sessionId
 			};
 			const response = await this.post("/api/exists", data);
-			this.logSuccess("Path existence checked", `${path} (exists: ${response.exists})`);
+			this.logSuccess("Path existence checked", `${path$1} (exists: ${response.exists})`);
 			return response;
 		} catch (error) {
 			this.logError("exists", error);
@@ -3026,6 +3029,401 @@ var CodeInterpreter = class {
 	}
 };
 
+//#endregion
+//#region src/sse-parser.ts
+/**
+* Server-Sent Events (SSE) parser for streaming responses
+* Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
+*/
+/**
+* Parse a ReadableStream of SSE events into typed AsyncIterable
+* @param stream - The ReadableStream from fetch response
+* @param signal - Optional AbortSignal for cancellation
+*/
+async function* parseSSEStream(stream, signal) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let currentEvent = { data: [] };
+	let isAborted = signal?.aborted ?? false;
+	const emitEvent = (data) => {
+		if (data === "[DONE]" || data.trim() === "") return;
+		try {
+			return JSON.parse(data);
+		} catch {
+			return;
+		}
+	};
+	const onAbort = () => {
+		isAborted = true;
+		reader.cancel().catch(() => {});
+	};
+	if (signal && !signal.aborted) signal.addEventListener("abort", onAbort);
+	try {
+		while (true) {
+			if (isAborted) throw new Error("Operation was aborted");
+			const { done, value } = await reader.read();
+			if (isAborted) throw new Error("Operation was aborted");
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const parsed = parseSSEFrames(buffer, currentEvent);
+			buffer = parsed.remaining;
+			currentEvent = parsed.currentEvent;
+			for (const frame of parsed.events) {
+				const event = emitEvent(frame.data);
+				if (event !== void 0) yield event;
+			}
+		}
+		if (isAborted) throw new Error("Operation was aborted");
+		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+		for (const frame of finalParsed.events) {
+			const event = emitEvent(frame.data);
+			if (event !== void 0) yield event;
+		}
+	} finally {
+		if (signal) signal.removeEventListener("abort", onAbort);
+		try {
+			await reader.cancel();
+		} catch {}
+		reader.releaseLock();
+	}
+}
+/**
+* Helper to convert a Response with SSE stream directly to AsyncIterable
+* @param response - Response object with SSE stream
+* @param signal - Optional AbortSignal for cancellation
+*/
+async function* responseToAsyncIterable(response, signal) {
+	if (!response.ok) throw new Error(`Response not ok: ${response.status} ${response.statusText}`);
+	if (!response.body) throw new Error("No response body");
+	yield* parseSSEStream(response.body, signal);
+}
+/**
+* Create an SSE-formatted ReadableStream from an AsyncIterable
+* (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
+* @param events - AsyncIterable of events
+* @param options - Stream options
+*/
+function asyncIterableToSSEStream(events, options) {
+	const encoder = new TextEncoder();
+	const serialize = options?.serialize || JSON.stringify;
+	return new ReadableStream({
+		async start(controller) {
+			try {
+				for await (const event of events) {
+					if (options?.signal?.aborted) {
+						controller.error(/* @__PURE__ */ new Error("Operation was aborted"));
+						break;
+					}
+					const sseEvent = `data: ${serialize(event)}\n\n`;
+					controller.enqueue(encoder.encode(sseEvent));
+				}
+				controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+			} catch (error) {
+				controller.error(error);
+			} finally {
+				controller.close();
+			}
+		},
+		cancel() {}
+	});
+}
+
+//#endregion
+//#region src/local-mount-sync.ts
+const DEFAULT_POLL_INTERVAL_MS = 1e3;
+const DEFAULT_ECHO_SUPPRESS_TTL_MS = 2e3;
+const MAX_BACKOFF_MS = 3e4;
+const SYNC_CONCURRENCY = 5;
+/**
+* Manages bidirectional sync between an R2 binding and a container directory.
+*
+* R2 -> Container: polls bucket.list() to detect changes, then transfers diffs.
+* Container -> R2: uses inotifywait via the watch API to detect file changes.
+*/
+var LocalMountSyncManager = class {
+	bucket;
+	mountPath;
+	prefix;
+	readOnly;
+	client;
+	sessionId;
+	logger;
+	pollIntervalMs;
+	echoSuppressTtlMs;
+	snapshot = /* @__PURE__ */ new Map();
+	echoSuppressSet = /* @__PURE__ */ new Set();
+	pollTimer = null;
+	watchReconnectTimer = null;
+	watchAbortController = null;
+	running = false;
+	consecutivePollFailures = 0;
+	consecutiveWatchFailures = 0;
+	constructor(options) {
+		this.bucket = options.bucket;
+		this.mountPath = options.mountPath;
+		this.prefix = options.prefix;
+		this.readOnly = options.readOnly;
+		this.client = options.client;
+		this.sessionId = options.sessionId;
+		this.logger = options.logger.child({ operation: "local-mount-sync" });
+		this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+		this.echoSuppressTtlMs = options.echoSuppressTtlMs ?? DEFAULT_ECHO_SUPPRESS_TTL_MS;
+	}
+	/**
+	* Start bidirectional sync. Performs initial full sync, then starts
+	* the R2 poll loop and (if not readOnly) the container watch loop.
+	*/
+	async start() {
+		this.running = true;
+		await this.client.files.mkdir(this.mountPath, this.sessionId, { recursive: true });
+		await this.fullSyncR2ToContainer();
+		this.schedulePoll();
+		if (!this.readOnly) this.startContainerWatch();
+		this.logger.info("Local mount sync started", {
+			mountPath: this.mountPath,
+			prefix: this.prefix,
+			readOnly: this.readOnly,
+			pollIntervalMs: this.pollIntervalMs
+		});
+	}
+	/**
+	* Stop all sync activity and clean up resources.
+	*/
+	async stop() {
+		this.running = false;
+		if (this.pollTimer) {
+			clearTimeout(this.pollTimer);
+			this.pollTimer = null;
+		}
+		if (this.watchReconnectTimer) {
+			clearTimeout(this.watchReconnectTimer);
+			this.watchReconnectTimer = null;
+		}
+		if (this.watchAbortController) {
+			this.watchAbortController.abort();
+			this.watchAbortController = null;
+		}
+		this.snapshot.clear();
+		this.echoSuppressSet.clear();
+		this.logger.info("Local mount sync stopped", { mountPath: this.mountPath });
+	}
+	async fullSyncR2ToContainer() {
+		const objects = await this.listAllR2Objects();
+		const newSnapshot = /* @__PURE__ */ new Map();
+		for (let i = 0; i < objects.length; i += SYNC_CONCURRENCY) {
+			const batch = objects.slice(i, i + SYNC_CONCURRENCY);
+			await Promise.all(batch.map(async (obj) => {
+				const containerPath = this.r2KeyToContainerPath(obj.key);
+				newSnapshot.set(obj.key, {
+					etag: obj.etag,
+					size: obj.size
+				});
+				await this.ensureParentDir(containerPath);
+				await this.transferR2ObjectToContainer(obj.key, containerPath);
+			}));
+		}
+		this.snapshot = newSnapshot;
+		this.logger.debug("Initial R2 -> Container sync complete", { objectCount: objects.length });
+	}
+	schedulePoll() {
+		if (!this.running) return;
+		const backoffMs = this.consecutivePollFailures > 0 ? Math.min(this.pollIntervalMs * 2 ** this.consecutivePollFailures, MAX_BACKOFF_MS) : this.pollIntervalMs;
+		this.pollTimer = setTimeout(async () => {
+			try {
+				await this.pollR2ForChanges();
+				this.consecutivePollFailures = 0;
+			} catch (error) {
+				this.consecutivePollFailures++;
+				this.logger.error("R2 poll cycle failed", error instanceof Error ? error : new Error(String(error)));
+			}
+			this.schedulePoll();
+		}, backoffMs);
+	}
+	async pollR2ForChanges() {
+		const objects = await this.listAllR2Objects();
+		const newSnapshot = /* @__PURE__ */ new Map();
+		const changed = [];
+		for (const obj of objects) {
+			newSnapshot.set(obj.key, {
+				etag: obj.etag,
+				size: obj.size
+			});
+			const existing = this.snapshot.get(obj.key);
+			if (!existing || existing.etag !== obj.etag) changed.push({
+				key: obj.key,
+				action: existing ? "modified" : "created"
+			});
+		}
+		for (let i = 0; i < changed.length; i += SYNC_CONCURRENCY) {
+			const batch = changed.slice(i, i + SYNC_CONCURRENCY);
+			await Promise.all(batch.map(async ({ key, action }) => {
+				try {
+					const containerPath = this.r2KeyToContainerPath(key);
+					await this.ensureParentDir(containerPath);
+					this.suppressEcho(containerPath);
+					await this.transferR2ObjectToContainer(key, containerPath);
+					this.logger.debug("R2 -> Container: synced object", {
+						key,
+						action
+					});
+				} catch (error) {
+					this.logger.error(`R2 -> Container: failed to sync object ${key}`, error instanceof Error ? error : new Error(String(error)));
+				}
+			}));
+		}
+		for (const [key] of this.snapshot) if (!newSnapshot.has(key)) {
+			const containerPath = this.r2KeyToContainerPath(key);
+			this.suppressEcho(containerPath);
+			try {
+				await this.client.files.deleteFile(containerPath, this.sessionId);
+				this.logger.debug("R2 -> Container: deleted file", { key });
+			} catch (error) {
+				this.logger.error("R2 -> Container: failed to delete", error instanceof Error ? error : new Error(String(error)));
+			}
+		}
+		this.snapshot = newSnapshot;
+	}
+	async listAllR2Objects() {
+		const results = [];
+		let cursor;
+		do {
+			const listResult = await this.bucket.list({
+				...this.prefix && { prefix: this.prefix },
+				...cursor && { cursor }
+			});
+			for (const obj of listResult.objects) results.push({
+				key: obj.key,
+				etag: obj.etag,
+				size: obj.size
+			});
+			cursor = listResult.truncated ? listResult.cursor : void 0;
+		} while (cursor);
+		return results;
+	}
+	async transferR2ObjectToContainer(key, containerPath) {
+		const obj = await this.bucket.get(key);
+		if (!obj) return;
+		const arrayBuffer = await obj.arrayBuffer();
+		const base64 = uint8ArrayToBase64(new Uint8Array(arrayBuffer));
+		await this.client.files.writeFile(containerPath, base64, this.sessionId, { encoding: "base64" });
+	}
+	async ensureParentDir(containerPath) {
+		const parentDir = containerPath.substring(0, containerPath.lastIndexOf("/"));
+		if (parentDir && parentDir !== this.mountPath) await this.client.files.mkdir(parentDir, this.sessionId, { recursive: true });
+	}
+	startContainerWatch() {
+		this.watchAbortController = new AbortController();
+		this.runWatchWithRetry();
+	}
+	runWatchWithRetry() {
+		if (!this.running) return;
+		this.runContainerWatchLoop().then(() => {
+			this.consecutiveWatchFailures = 0;
+			this.scheduleWatchReconnect();
+		}).catch((error) => {
+			if (!this.running) return;
+			this.consecutiveWatchFailures++;
+			this.logger.error("Container watch loop failed", error instanceof Error ? error : new Error(String(error)));
+			this.scheduleWatchReconnect();
+		});
+	}
+	scheduleWatchReconnect() {
+		if (!this.running) return;
+		const backoffMs = this.consecutiveWatchFailures > 0 ? Math.min(this.pollIntervalMs * 2 ** this.consecutiveWatchFailures, MAX_BACKOFF_MS) : this.pollIntervalMs;
+		this.logger.debug("Reconnecting container watch", {
+			backoffMs,
+			failures: this.consecutiveWatchFailures
+		});
+		this.watchReconnectTimer = setTimeout(() => {
+			this.watchReconnectTimer = null;
+			if (!this.running) return;
+			this.watchAbortController = new AbortController();
+			this.runWatchWithRetry();
+		}, backoffMs);
+	}
+	async runContainerWatchLoop() {
+		const stream = await this.client.watch.watch({
+			path: this.mountPath,
+			recursive: true,
+			sessionId: this.sessionId
+		});
+		for await (const event of parseSSEStream(stream, this.watchAbortController?.signal)) {
+			if (!this.running) break;
+			this.consecutiveWatchFailures = 0;
+			if (event.type !== "event") continue;
+			if (event.isDirectory) continue;
+			const containerPath = event.path;
+			if (this.echoSuppressSet.has(containerPath)) continue;
+			const r2Key = this.containerPathToR2Key(containerPath);
+			if (!r2Key) continue;
+			try {
+				switch (event.eventType) {
+					case "create":
+					case "modify":
+					case "move_to":
+						await this.uploadFileToR2(containerPath, r2Key);
+						this.logger.debug("Container -> R2: synced file", {
+							path: containerPath,
+							key: r2Key,
+							action: event.eventType
+						});
+						break;
+					case "delete":
+					case "move_from":
+						await this.bucket.delete(r2Key);
+						this.snapshot.delete(r2Key);
+						this.logger.debug("Container -> R2: deleted object", {
+							path: containerPath,
+							key: r2Key
+						});
+						break;
+				}
+			} catch (error) {
+				this.logger.error(`Container -> R2 sync failed for ${containerPath}`, error instanceof Error ? error : new Error(String(error)));
+			}
+		}
+	}
+	/**
+	* Read a container file and upload it to R2, then update the local
+	* snapshot so the next poll cycle doesn't echo the write back.
+	*/
+	async uploadFileToR2(containerPath, r2Key) {
+		const bytes = base64ToUint8Array((await this.client.files.readFile(containerPath, this.sessionId, { encoding: "base64" })).content);
+		await this.bucket.put(r2Key, bytes);
+		const head = await this.bucket.head(r2Key);
+		if (head) this.snapshot.set(r2Key, {
+			etag: head.etag,
+			size: head.size
+		});
+	}
+	suppressEcho(containerPath) {
+		this.echoSuppressSet.add(containerPath);
+		setTimeout(() => {
+			this.echoSuppressSet.delete(containerPath);
+		}, this.echoSuppressTtlMs);
+	}
+	r2KeyToContainerPath(key) {
+		let relativePath = key;
+		if (this.prefix) relativePath = key.startsWith(this.prefix) ? key.slice(this.prefix.length) : key;
+		return path.join(this.mountPath, relativePath);
+	}
+	containerPathToR2Key(containerPath) {
+		const resolved = path.resolve(containerPath);
+		const mount = path.resolve(this.mountPath);
+		if (!resolved.startsWith(mount)) return null;
+		const relativePath = path.relative(mount, resolved);
+		if (!relativePath || relativePath.startsWith("..")) return null;
+		return this.prefix ? path.join(this.prefix, relativePath) : relativePath;
+	}
+};
+function uint8ArrayToBase64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+function base64ToUint8Array(base64) {
+	return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
 //#endregion
 //#region src/pty/proxy.ts
 async function proxyTerminal(stub, sessionId, request, options) {
@@ -3052,14 +3450,14 @@ async function proxyToSandbox(request, env) {
 		const url = new URL(request.url);
 		const routeInfo = extractSandboxRoute(url);
 		if (!routeInfo) return null;
-		const { sandboxId, port, path, token } = routeInfo;
+		const { sandboxId, port, path: path$1, token } = routeInfo;
 		const sandbox = getSandbox(env.Sandbox, sandboxId, { normalizeId: true });
 		if (port !== 3e3) {
 			if (!await sandbox.validatePortToken(port, token)) {
 				logger.warn("Invalid token access blocked", {
 					port,
 					sandboxId,
-					path,
+					path: path$1,
 					hostname: url.hostname,
 					url: request.url,
 					method: request.method,
@@ -3076,8 +3474,8 @@ async function proxyToSandbox(request, env) {
 		}
 		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") return await sandbox.fetch(switchPort(request, port));
 		let proxyUrl;
-		if (port !== 3e3) proxyUrl = `http://localhost:${port}${path}${url.search}`;
-		else proxyUrl = `http://localhost:3000${path}${url.search}`;
+		if (port !== 3e3) proxyUrl = `http://localhost:${port}${path$1}${url.search}`;
+		else proxyUrl = `http://localhost:3000${path$1}${url.search}`;
 		const headers = {
 			"X-Original-URL": request.url,
 			"X-Forwarded-Host": url.hostname,
@@ -3139,106 +3537,6 @@ function isLocalhostPattern(hostname) {
 	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
 }
 
-//#endregion
-//#region src/sse-parser.ts
-/**
-* Server-Sent Events (SSE) parser for streaming responses
-* Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
-*/
-/**
-* Parse a ReadableStream of SSE events into typed AsyncIterable
-* @param stream - The ReadableStream from fetch response
-* @param signal - Optional AbortSignal for cancellation
-*/
-async function* parseSSEStream(stream, signal) {
-	const reader = stream.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	let currentEvent = { data: [] };
-	let isAborted = signal?.aborted ?? false;
-	const emitEvent = (data) => {
-		if (data === "[DONE]" || data.trim() === "") return;
-		try {
-			return JSON.parse(data);
-		} catch {
-			return;
-		}
-	};
-	const onAbort = () => {
-		isAborted = true;
-		reader.cancel().catch(() => {});
-	};
-	if (signal && !signal.aborted) signal.addEventListener("abort", onAbort);
-	try {
-		while (true) {
-			if (isAborted) throw new Error("Operation was aborted");
-			const { done, value } = await reader.read();
-			if (isAborted) throw new Error("Operation was aborted");
-			if (done) break;
-			buffer += decoder.decode(value, { stream: true });
-			const parsed = parseSSEFrames(buffer, currentEvent);
-			buffer = parsed.remaining;
-			currentEvent = parsed.currentEvent;
-			for (const frame of parsed.events) {
-				const event = emitEvent(frame.data);
-				if (event !== void 0) yield event;
-			}
-		}
-		if (isAborted) throw new Error("Operation was aborted");
-		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
-		for (const frame of finalParsed.events) {
-			const event = emitEvent(frame.data);
-			if (event !== void 0) yield event;
-		}
-	} finally {
-		if (signal) signal.removeEventListener("abort", onAbort);
-		try {
-			await reader.cancel();
-		} catch {}
-		reader.releaseLock();
-	}
-}
-/**
-* Helper to convert a Response with SSE stream directly to AsyncIterable
-* @param response - Response object with SSE stream
-* @param signal - Optional AbortSignal for cancellation
-*/
-async function* responseToAsyncIterable(response, signal) {
-	if (!response.ok) throw new Error(`Response not ok: ${response.status} ${response.statusText}`);
-	if (!response.body) throw new Error("No response body");
-	yield* parseSSEStream(response.body, signal);
-}
-/**
-* Create an SSE-formatted ReadableStream from an AsyncIterable
-* (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
-* @param events - AsyncIterable of events
-* @param options - Stream options
-*/
-function asyncIterableToSSEStream(events, options) {
-	const encoder = new TextEncoder();
-	const serialize = options?.serialize || JSON.stringify;
-	return new ReadableStream({
-		async start(controller) {
-			try {
-				for await (const event of events) {
-					if (options?.signal?.aborted) {
-						controller.error(/* @__PURE__ */ new Error("Operation was aborted"));
-						break;
-					}
-					const sseEvent = `data: ${serialize(event)}\n\n`;
-					controller.enqueue(encoder.encode(sseEvent));
-				}
-				controller.enqueue(encoder.encode("data: [DONE]\n\n"));
-			} catch (error) {
-				controller.error(error);
-			} finally {
-				controller.close();
-			}
-		},
-		cancel() {}
-	});
-}
-
 //#endregion
 //#region src/storage-mount/errors.ts
 /**
@@ -3388,21 +3686,79 @@ function buildS3fsSource(bucket, prefix) {
 * 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.7.16";
+const SDK_VERSION = "0.7.18";
 
 //#endregion
 //#region src/sandbox.ts
+const sandboxConfigurationCache = /* @__PURE__ */ new WeakMap();
+function getNamespaceConfigurationCache(namespace) {
+	const existing = sandboxConfigurationCache.get(namespace);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	sandboxConfigurationCache.set(namespace, created);
+	return created;
+}
+function sameContainerTimeouts(left, right) {
+	return left?.instanceGetTimeoutMS === right?.instanceGetTimeoutMS && left?.portReadyTimeoutMS === right?.portReadyTimeoutMS && left?.waitIntervalMS === right?.waitIntervalMS;
+}
+function buildSandboxConfiguration(effectiveId, options, cached) {
+	const configuration = {};
+	if (cached?.sandboxName !== effectiveId || cached.normalizeId !== options?.normalizeId) configuration.sandboxName = {
+		name: effectiveId,
+		normalizeId: options?.normalizeId
+	};
+	if (options?.baseUrl !== void 0 && cached?.baseUrl !== options.baseUrl) configuration.baseUrl = options.baseUrl;
+	if (options?.sleepAfter !== void 0 && cached?.sleepAfter !== options.sleepAfter) configuration.sleepAfter = options.sleepAfter;
+	if (options?.keepAlive !== void 0 && cached?.keepAlive !== options.keepAlive) configuration.keepAlive = options.keepAlive;
+	if (options?.containerTimeouts && !sameContainerTimeouts(cached?.containerTimeouts, options.containerTimeouts)) configuration.containerTimeouts = options.containerTimeouts;
+	return configuration;
+}
+function hasSandboxConfiguration(configuration) {
+	return configuration.sandboxName !== void 0 || configuration.baseUrl !== void 0 || configuration.sleepAfter !== void 0 || configuration.keepAlive !== void 0 || configuration.containerTimeouts !== void 0;
+}
+function mergeSandboxConfiguration(cached, configuration) {
+	return {
+		...cached,
+		...configuration.sandboxName && {
+			sandboxName: configuration.sandboxName.name,
+			normalizeId: configuration.sandboxName.normalizeId
+		},
+		...configuration.baseUrl !== void 0 && { baseUrl: configuration.baseUrl },
+		...configuration.sleepAfter !== void 0 && { sleepAfter: configuration.sleepAfter },
+		...configuration.keepAlive !== void 0 && { keepAlive: configuration.keepAlive },
+		...configuration.containerTimeouts !== void 0 && { containerTimeouts: configuration.containerTimeouts }
+	};
+}
+function applySandboxConfiguration(stub, configuration) {
+	if (stub.configure) return stub.configure(configuration);
+	const operations = [];
+	if (configuration.sandboxName) operations.push(stub.setSandboxName?.(configuration.sandboxName.name, configuration.sandboxName.normalizeId) ?? Promise.resolve());
+	if (configuration.baseUrl !== void 0) operations.push(stub.setBaseUrl?.(configuration.baseUrl) ?? Promise.resolve());
+	if (configuration.sleepAfter !== void 0) operations.push(stub.setSleepAfter?.(configuration.sleepAfter) ?? Promise.resolve());
+	if (configuration.keepAlive !== void 0) operations.push(stub.setKeepAlive?.(configuration.keepAlive) ?? Promise.resolve());
+	if (configuration.containerTimeouts !== void 0) operations.push(stub.setContainerTimeouts?.(configuration.containerTimeouts) ?? Promise.resolve());
+	return Promise.all(operations).then(() => void 0);
+}
 function getSandbox(ns, id, options) {
 	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);
+	const namespaceCache = getNamespaceConfigurationCache(ns);
+	const cachedConfiguration = namespaceCache.get(effectiveId);
+	const configuration = buildSandboxConfiguration(effectiveId, options, cachedConfiguration);
+	if (hasSandboxConfiguration(configuration)) {
+		const nextConfiguration = mergeSandboxConfiguration(cachedConfiguration, configuration);
+		namespaceCache.set(effectiveId, nextConfiguration);
+		applySandboxConfiguration(stub, configuration).catch(() => {
+			if (cachedConfiguration) {
+				namespaceCache.set(effectiveId, cachedConfiguration);
+				return;
+			}
+			namespaceCache.delete(effectiveId);
+		});
+	}
 	const defaultSessionId = `sandbox-${effectiveId}`;
 	const enhancedMethods = {
 		fetch: (request) => stub.fetch(request),
@@ -3616,6 +3972,13 @@ var Sandbox = class Sandbox extends Container {
 			await this.ctx.storage.put("normalizeId", this.normalizeId);
 		}
 	}
+	async configure(configuration) {
+		if (configuration.sandboxName) await this.setSandboxName(configuration.sandboxName.name, configuration.sandboxName.normalizeId);
+		if (configuration.baseUrl !== void 0) await this.setBaseUrl(configuration.baseUrl);
+		if (configuration.sleepAfter !== void 0) await this.setSleepAfter(configuration.sleepAfter);
+		if (configuration.keepAlive !== void 0) await this.setKeepAlive(configuration.keepAlive);
+		if (configuration.containerTimeouts !== void 0) await this.setContainerTimeouts(configuration.containerTimeouts);
+	}
 	async setBaseUrl(baseUrl) {
 		if (!this.baseUrl) {
 			this.baseUrl = baseUrl;
@@ -3698,8 +4061,67 @@ var Sandbox = class Sandbox extends Container {
 			waitIntervalMS: parseAndValidate(getEnvString(env, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
 		};
 	}
+	/**
+	* Mount an S3-compatible bucket as a local directory.
+	*
+	* Requires explicit endpoint URL for production. Credentials are auto-detected from environment
+	* variables or can be provided explicitly.
+	*
+	* @param bucket - Bucket name (or R2 binding name when localBucket is true)
+	* @param mountPath - Absolute path in container to mount at
+	* @param options - Mount configuration
+	* @throws MissingCredentialsError if no credentials found in environment
+	* @throws S3FSMountError if S3FS mount command fails
+	* @throws InvalidMountConfigError if bucket name, mount path, or endpoint is invalid
+	*/
 	async mountBucket(bucket, mountPath, options) {
 		this.logger.info(`Mounting bucket ${bucket} to ${mountPath}`);
+		if ("localBucket" in options && options.localBucket) {
+			await this.mountBucketLocal(bucket, mountPath, options);
+			return;
+		}
+		await this.mountBucketFuse(bucket, mountPath, options);
+	}
+	/**
+	* Local dev mount: bidirectional sync via R2 binding + file/watch APIs
+	*/
+	async mountBucketLocal(bucket, mountPath, options) {
+		const r2Binding = this.env[bucket];
+		if (!r2Binding || !isR2Bucket(r2Binding)) throw new InvalidMountConfigError(`R2 binding "${bucket}" not found in env or is not an R2Bucket. Make sure the binding name matches your wrangler.jsonc R2 binding.`);
+		if (!mountPath || !mountPath.startsWith("/")) throw new InvalidMountConfigError(`Invalid mount path: "${mountPath}". Must be an absolute path starting with /`);
+		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path already in use: ${mountPath}`);
+		const sessionId = await this.ensureDefaultSession();
+		const syncManager = new LocalMountSyncManager({
+			bucket: r2Binding,
+			mountPath,
+			prefix: options.prefix,
+			readOnly: options.readOnly ?? false,
+			client: this.client,
+			sessionId,
+			logger: this.logger
+		});
+		const mountInfo = {
+			mountType: "local-sync",
+			bucket,
+			mountPath,
+			syncManager,
+			mounted: false
+		};
+		this.activeMounts.set(mountPath, mountInfo);
+		try {
+			await syncManager.start();
+			mountInfo.mounted = true;
+			this.logger.info(`Successfully mounted bucket ${bucket} to ${mountPath} (local sync)`);
+		} catch (error) {
+			await syncManager.stop();
+			this.activeMounts.delete(mountPath);
+			throw error;
+		}
+	}
+	/**
+	* Production mount: S3FS-FUSE inside the container
+	*/
+	async mountBucketFuse(bucket, mountPath, options) {
 		const prefix = options.prefix || void 0;
 		this.validateMountOptions(bucket, mountPath, {
 			...options,
@@ -3713,26 +4135,21 @@ var Sandbox = class Sandbox extends Container {
 		});
 		const credentials = detectCredentials(options, this.envVars);
 		const passwordFilePath = this.generatePasswordFilePath();
-		this.activeMounts.set(mountPath, {
+		const mountInfo = {
+			mountType: "fuse",
 			bucket: s3fsSource,
 			mountPath,
 			endpoint: options.endpoint,
 			provider,
 			passwordFilePath,
 			mounted: false
-		});
+		};
+		this.activeMounts.set(mountPath, mountInfo);
 		try {
 			await this.createPasswordFile(passwordFilePath, bucket, credentials);
 			await this.exec(`mkdir -p ${shellEscape(mountPath)}`);
 			await this.executeS3FSMount(s3fsSource, mountPath, options, provider, passwordFilePath);
-			this.activeMounts.set(mountPath, {
-				bucket: s3fsSource,
-				mountPath,
-				endpoint: options.endpoint,
-				provider,
-				passwordFilePath,
-				mounted: true
-			});
+			mountInfo.mounted = true;
 			this.logger.info(`Successfully mounted bucket ${bucket} to ${mountPath}`);
 		} catch (error) {
 			await this.deletePasswordFile(passwordFilePath);
@@ -3750,7 +4167,11 @@ var Sandbox = class Sandbox extends Container {
 		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 {
+		if (mountInfo.mountType === "local-sync") {
+			await mountInfo.syncManager.stop();
+			mountInfo.mounted = false;
+			this.activeMounts.delete(mountPath);
+		} else try {
 			await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
 			mountInfo.mounted = false;
 			this.activeMounts.delete(mountPath);
@@ -3763,7 +4184,6 @@ var Sandbox = class Sandbox extends Container {
 	* 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) {
@@ -3832,7 +4252,14 @@ var Sandbox = class Sandbox extends Container {
 			await this.client.desktop.stop();
 		} catch {}
 		this.client.disconnect();
-		for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
+		for (const [mountPath, mountInfo] of this.activeMounts.entries()) if (mountInfo.mountType === "local-sync") try {
+			await mountInfo.syncManager.stop();
+			mountInfo.mounted = false;
+		} catch (error) {
+			const errorMsg = error instanceof Error ? error.message : String(error);
+			this.logger.warn(`Failed to stop local sync for ${mountPath}: ${errorMsg}`);
+		}
+		else {
 			if (mountInfo.mounted) try {
 				this.logger.info(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
 				await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
@@ -3876,6 +4303,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async onStop() {
 		this.logger.debug("Sandbox stopped");
+		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
 		this.defaultSession = null;
 		this.activeMounts.clear();
 		await Promise.all([this.ctx.storage.delete("portTokens"), this.ctx.storage.delete("defaultSession")]);
@@ -4350,17 +4778,17 @@ var Sandbox = class Sandbox extends Container {
 	* Wait for a port to become available (for process readiness checking)
 	*/
 	async waitForPortReady(processId, command, port, options) {
-		const { mode = "http", path = "/", status = {
+		const { mode = "http", path: path$1 = "/", status = {
 			min: 200,
 			max: 399
 		}, timeout, interval = 500 } = options ?? {};
-		const conditionStr = mode === "http" ? `port ${port} (HTTP ${path})` : `port ${port} (TCP)`;
+		const conditionStr = mode === "http" ? `port ${port} (HTTP ${path$1})` : `port ${port} (TCP)`;
 		const statusMin = typeof status === "number" ? status : status.min;
 		const statusMax = typeof status === "number" ? status : status.max;
 		const stream = await this.client.ports.watchPort({
 			port,
 			mode,
-			path,
+			path: path$1,
 			statusMin,
 			statusMax,
 			processId,
@@ -4620,17 +5048,17 @@ var Sandbox = class Sandbox extends Container {
 			depth: options?.depth
 		});
 	}
-	async mkdir(path, options = {}) {
+	async mkdir(path$1, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.mkdir(path, session, { recursive: options.recursive });
+		return this.client.files.mkdir(path$1, session, { recursive: options.recursive });
 	}
-	async writeFile(path, content, options = {}) {
+	async writeFile(path$1, content, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.writeFile(path, content, session, { encoding: options.encoding });
+		return this.client.files.writeFile(path$1, content, session, { encoding: options.encoding });
 	}
-	async deleteFile(path, sessionId) {
+	async deleteFile(path$1, sessionId) {
 		const session = sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.deleteFile(path, session);
+		return this.client.files.deleteFile(path$1, session);
 	}
 	async renameFile(oldPath, newPath, sessionId) {
 		const session = sessionId ?? await this.ensureDefaultSession();
@@ -4640,9 +5068,9 @@ var Sandbox = class Sandbox extends Container {
 		const session = sessionId ?? await this.ensureDefaultSession();
 		return this.client.files.moveFile(sourcePath, destinationPath, session);
 	}
-	async readFile(path, options = {}) {
+	async readFile(path$1, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.readFile(path, session, { encoding: options.encoding });
+		return this.client.files.readFile(path$1, session, { encoding: options.encoding });
 	}
 	/**
 	* Stream a file from the sandbox using Server-Sent Events
@@ -4650,17 +5078,17 @@ var Sandbox = class Sandbox extends Container {
 	* @param path - Path to the file to stream
 	* @param options - Optional session ID
 	*/
-	async readFileStream(path, options = {}) {
+	async readFileStream(path$1, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.readFileStream(path, session);
+		return this.client.files.readFileStream(path$1, session);
 	}
-	async listFiles(path, options) {
+	async listFiles(path$1, options) {
 		const session = await this.ensureDefaultSession();
-		return this.client.files.listFiles(path, session, options);
+		return this.client.files.listFiles(path$1, session, options);
 	}
-	async exists(path, sessionId) {
+	async exists(path$1, sessionId) {
 		const session = sessionId ?? await this.ensureDefaultSession();
-		return this.client.files.exists(path, session);
+		return this.client.files.exists(path$1, session);
 	}
 	/**
 	* Get the noVNC preview URL for browser-based desktop viewing.
@@ -4709,10 +5137,10 @@ var Sandbox = class Sandbox extends Container {
 	* @param path - Path to watch (absolute or relative to /workspace)
 	* @param options - Watch options
 	*/
-	async watch(path, options = {}) {
+	async watch(path$1, options = {}) {
 		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
 		return this.client.watch.watch({
-			path,
+			path: path$1,
 			recursive: options.recursive,
 			include: options.include,
 			exclude: options.exclude,
@@ -4921,28 +5349,28 @@ var Sandbox = class Sandbox extends Container {
 			cleanupCompletedProcesses: () => this.cleanupCompletedProcesses(),
 			getProcessLogs: (id) => this.getProcessLogs(id),
 			streamProcessLogs: (processId, options) => this.streamProcessLogs(processId, options),
-			writeFile: (path, content, options) => this.writeFile(path, content, {
+			writeFile: (path$1, content, options) => this.writeFile(path$1, content, {
 				...options,
 				sessionId
 			}),
-			readFile: (path, options) => this.readFile(path, {
+			readFile: (path$1, options) => this.readFile(path$1, {
 				...options,
 				sessionId
 			}),
-			readFileStream: (path) => this.readFileStream(path, { sessionId }),
-			watch: (path, options) => this.watch(path, {
+			readFileStream: (path$1) => this.readFileStream(path$1, { sessionId }),
+			watch: (path$1, options) => this.watch(path$1, {
 				...options,
 				sessionId
 			}),
-			mkdir: (path, options) => this.mkdir(path, {
+			mkdir: (path$1, options) => this.mkdir(path$1, {
 				...options,
 				sessionId
 			}),
-			deleteFile: (path) => this.deleteFile(path, sessionId),
+			deleteFile: (path$1) => this.deleteFile(path$1, sessionId),
 			renameFile: (oldPath, newPath) => this.renameFile(oldPath, newPath, sessionId),
 			moveFile: (sourcePath, destPath) => this.moveFile(sourcePath, destPath, sessionId),
-			listFiles: (path, options) => this.client.files.listFiles(path, sessionId, options),
-			exists: (path) => this.exists(path, sessionId),
+			listFiles: (path$1, options) => this.client.files.listFiles(path$1, sessionId, options),
+			exists: (path$1) => this.exists(path$1, sessionId),
 			gitCheckout: (repoUrl, options) => this.gitCheckout(repoUrl, {
 				...options,
 				sessionId
@@ -5259,7 +5687,7 @@ var Sandbox = class Sandbox extends Container {
 		this.requirePresignedUrlSupport();
 		const DEFAULT_TTL_SECONDS = 259200;
 		const MAX_NAME_LENGTH = 256;
-		const { dir, name, ttl = DEFAULT_TTL_SECONDS } = options;
+		const { dir, name, ttl = DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
 		Sandbox.validateBackupDir(dir, "BackupOptions.dir");
 		if (name !== void 0) {
 			if (typeof name !== "string" || name.length > MAX_NAME_LENGTH) throw new InvalidBackupConfigError({
@@ -5284,15 +5712,31 @@ var Sandbox = class Sandbox extends Container {
 			context: { reason: "ttl must be a positive number of seconds" },
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
+		if (typeof gitignore !== "boolean") throw new InvalidBackupConfigError({
+			message: "BackupOptions.gitignore must be a boolean",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "gitignore must be a boolean" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (!Array.isArray(excludes) || !excludes.every((e) => typeof e === "string")) throw new InvalidBackupConfigError({
+			message: "BackupOptions.excludes must be an array of strings",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "excludes must be an array of strings" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 		const backupSession = await this.ensureBackupSession();
 		const backupId = crypto.randomUUID();
 		const archivePath = `/var/backups/${backupId}.sqsh`;
 		this.logger.info("Creating backup", {
 			backupId,
 			dir,
-			name
+			name,
+			gitignore,
+			excludes
 		});
-		const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession);
+		const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, gitignore, excludes);
 		if (!createResult.success) throw new BackupCreateError({
 			message: "Container failed to create backup archive",
 			code: ErrorCode.BACKUP_CREATE_FAILED,