@cloudflare/sandbox 0.10.2 → 0.11.0

package/dist/{sandbox-BcEq4aUF.js → sandbox-DQxTkLyY.js}

@@ -1,5 +1,5 @@
 import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
-import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-8Hvune8K.js";
+import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-COsTRno_.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import { RpcSession, RpcTarget } from "capnweb";
@@ -231,7 +231,7 @@ var SessionTerminatedError = class extends SandboxError {
 	}
 };
 /**
-* Error thrown when a port is already exposed
+* Compatibility error for legacy port exposure registry responses.
 */
 var PortAlreadyExposedError = class extends SandboxError {
 	constructor(errorResponse) {
@@ -246,7 +246,7 @@ var PortAlreadyExposedError = class extends SandboxError {
 	}
 };
 /**
-* Error thrown when a port is not exposed
+* Compatibility error for legacy port exposure registry responses.
 */
 var PortNotExposedError = class extends SandboxError {
 	constructor(errorResponse) {
@@ -2365,40 +2365,9 @@ var InterpreterClient = class extends BaseHttpClient {
 //#endregion
 //#region src/clients/port-client.ts
 /**
-* Client for port management and preview URL operations
+* Client for port readiness operations.
 */
 var PortClient = class extends BaseHttpClient {
-	/**
-	* Expose a port and get a preview URL
-	* @param port - Port number to expose
-	* @param sessionId - The session ID for this operation
-	* @param name - Optional name for the port
-	*/
-	async exposePort(port, sessionId, name) {
-		const data = {
-			port,
-			sessionId,
-			name
-		};
-		return await this.post("/api/expose-port", data);
-	}
-	/**
-	* Unexpose a port and remove its preview URL
-	* @param port - Port number to unexpose
-	* @param sessionId - The session ID for this operation
-	*/
-	async unexposePort(port, sessionId) {
-		const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
-		return await this.delete(url);
-	}
-	/**
-	* Get all currently exposed ports
-	* @param sessionId - The session ID for this operation
-	*/
-	async getExposedPorts(sessionId) {
-		const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
-		return await this.get(url);
-	}
 	/**
 	* Watch a port for readiness via SSE stream
 	* @param request - Port watch configuration
@@ -2765,6 +2734,10 @@ function normalizeBackupExcludePattern(pattern) {
 	return normalized;
 }
 
+//#endregion
+//#region ../shared/src/internal.ts
+const DISABLE_SESSION_TOKEN = "__DISABLE_SESSION__";
+
 //#endregion
 //#region src/container-control/connection.ts
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -3057,12 +3030,33 @@ const IDLE_EXPORT_THRESHOLD = 1;
 /**
 * Translate a capnweb-propagated error into a typed SandboxError.
 *
-* capnweb only preserves `error.name` and `error.message` across the wire.
-* The container encodes the full error as a JSON object in the message
-* string: `{"code":"...","message":"...","context":{...}}`.
+* Two wire formats are supported for backward compatibility with older
+* container images:
+*
+*  1. Propagated error properties (capnweb >= 0.8.0). The container throws a
+*     `ServiceError`-shaped object with own enumerable `code` and `details`
+*     properties. capnweb walks `Object.keys()` and reconstructs those fields
+*     on the SDK side.
+*  2. Legacy JSON-encoded message. Older containers encoded the structured
+*     payload as a JSON string in `error.message`.
+*
+* The JSON-fallback branch can be removed once all older container images are
+* no longer in service.
 */
 function translateRPCError(error) {
 	if (error instanceof Error) {
+		const propagated = error;
+		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
+			const code = propagated.code;
+			const context = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
+			throw createErrorFromResponse({
+				code,
+				message: error.message,
+				context,
+				httpStatus: getHttpStatus(code),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
 		let payload;
 		try {
 			payload = JSON.parse(error.message);
@@ -3365,6 +3359,89 @@ var ContainerControlClient = class {
 	}
 };
 
+//#endregion
+//#region src/current-runtime-identity.ts
+const CURRENT_RUNTIME_IDENTITY_STORAGE_KEY = "currentRuntimeIdentity";
+var RuntimeIdentityInactiveError = class extends Error {
+	constructor() {
+		super("Runtime identity is no longer active");
+		this.name = "RuntimeIdentityInactiveError";
+	}
+};
+var RuntimeIdentity = class {
+	id;
+	constructor(record) {
+		this.id = record.id;
+	}
+	owns(record) {
+		return record.runtimeIdentityID === this.id;
+	}
+	scope(value) {
+		return {
+			...value,
+			runtimeIdentityID: this.id
+		};
+	}
+};
+var CurrentRuntimeIdentity = class {
+	/**
+	* Runtime identity is stored in Durable Object storage so a reconstructed DO
+	* can still recognize the live container runtime it owns. In-memory state is
+	* only a cache and cannot define runtime-scoped correctness.
+	*/
+	constructor(storage, getContainerState, isContainerRunning) {
+		this.storage = storage;
+		this.getContainerState = getContainerState;
+		this.isContainerRunning = isContainerRunning;
+	}
+	async get() {
+		const status = await this.getStatus();
+		return status.status === "active" ? status.runtime : null;
+	}
+	async getStatus() {
+		const state = await this.getContainerState();
+		if (state.status !== "healthy") return {
+			status: "inactive",
+			reason: "runtime-not-healthy",
+			containerStatus: state.status
+		};
+		if (!this.isContainerRunning()) return {
+			status: "inactive",
+			reason: "runtime-not-running",
+			containerStatus: state.status
+		};
+		const runtime = await this.getStored();
+		if (!runtime) return {
+			status: "inactive",
+			reason: "missing-runtime-id",
+			containerStatus: state.status
+		};
+		return {
+			status: "active",
+			runtime,
+			containerStatus: state.status
+		};
+	}
+	async getStored(storage = this.storage) {
+		const record = await storage.get(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY) ?? null;
+		return record ? new RuntimeIdentity(record) : null;
+	}
+	async markStarted() {
+		const record = { id: crypto.randomUUID() };
+		await this.storage.put(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY, record);
+		return new RuntimeIdentity(record);
+	}
+	async clear() {
+		await this.storage.delete(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY);
+	}
+	async isActive(runtime) {
+		return (await this.get())?.id === runtime.id;
+	}
+	async assertActive(runtime) {
+		if (!await this.isActive(runtime)) throw new RuntimeIdentityInactiveError();
+	}
+};
+
 //#endregion
 //#region src/file-stream.ts
 /**
@@ -3557,6 +3634,32 @@ function validateLanguage(language) {
 	const normalized = language.toLowerCase();
 	if (!supportedLanguages.includes(normalized)) throw new SandboxSecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
 }
+/**
+* Validates a single DNS label for use as a Cloudflare Tunnel hostname.
+*
+* Used by `sandbox.tunnels.get(port, { name })` to reject obviously-bad
+* input client-side before any network call. Whether the chosen label is
+* actually available under the configured zone is left to the Cloudflare
+* API (returned as a typed error).
+*
+* Rules:
+* - 1–63 characters
+* - Lowercase letters, digits, and internal hyphens only
+* - No leading or trailing hyphen
+* - No dots — multi-label hostnames need a delegated subdomain zone or
+*   Advanced Certificate Manager, which are out of scope for this
+*   feature. Universal SSL only covers `<label>.<zone>`.
+*
+* Throws `SandboxSecurityError` on any violation. Designed to be called
+* before any other tunnel work so callers see a fast, deterministic
+* failure.
+*/
+const TUNNEL_NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validateTunnelName(name) {
+	if (typeof name !== "string") throw new SandboxSecurityError(`Tunnel name must be a string. Received: ${typeof name}`, "INVALID_TUNNEL_NAME");
+	if (name.length === 0 || name.length > 63) throw new SandboxSecurityError(`Tunnel name '${name}' must be 1–63 characters long.`, "INVALID_TUNNEL_NAME_LENGTH");
+	if (!TUNNEL_NAME_REGEX.test(name)) throw new SandboxSecurityError(`Tunnel name '${name}' is not a valid DNS label. Use lowercase letters, digits, and internal hyphens only (no dots, no leading/trailing hyphens).`, "INVALID_TUNNEL_NAME_FORMAT");
+}
 
 //#endregion
 //#region src/interpreter.ts
@@ -4212,118 +4315,138 @@ function base64ToUint8Array(base64) {
 }
 
 //#endregion
-//#region src/pty/proxy.ts
-async function proxyTerminal(stub, sessionId, request, options) {
-	if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId is required for terminal access");
-	if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") throw new Error("terminal() requires a WebSocket upgrade request");
-	const params = new URLSearchParams({ sessionId });
-	if (options?.cols) params.set("cols", String(options.cols));
-	if (options?.rows) params.set("rows", String(options.rows));
-	if (options?.shell) params.set("shell", options.shell);
-	const ptyUrl = `http://localhost/ws/pty?${params}`;
-	const ptyRequest = new Request(ptyUrl, request);
-	return stub.fetch(switchPort(ptyRequest, 3e3));
-}
-
-//#endregion
-//#region src/request-handler.ts
-async function proxyToSandbox(request, env$1) {
-	const logger = createLogger({
-		component: "sandbox-do",
-		traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
-		operation: "proxy"
-	});
+//#region src/preview-forwarding.ts
+async function forwardPreviewRequest(tcpPort, request, lifecycle) {
+	const containerURL = request.url.replace("https:", "http:");
+	const settleForward = lifecycle.beginForward();
 	try {
-		const url = new URL(request.url);
-		const routeInfo = extractSandboxRoute(url);
-		if (!routeInfo) return null;
-		const { sandboxId, port, path: path$1, token } = routeInfo;
-		const sandbox = getSandbox(env$1.Sandbox, sandboxId, { normalizeId: true });
-		if (port !== 3e3) {
-			if (!await sandbox.validatePortToken(port, token)) {
-				logger.warn("Invalid token access blocked", {
-					port,
-					sandboxId,
-					path: path$1,
-					hostname: url.hostname,
-					url: request.url,
-					method: request.method,
-					userAgent: request.headers.get("User-Agent") || "unknown"
-				});
-				return new Response(JSON.stringify({
-					error: `Access denied: Invalid token or port not exposed`,
-					code: "INVALID_TOKEN"
-				}), {
-					status: 404,
-					headers: { "Content-Type": "application/json" }
-				});
-			}
+		const response = await tcpPort.fetch(containerURL, request);
+		if (response.webSocket !== null) return {
+			status: "response",
+			response: bridgePreviewWebSocket(response, lifecycle, settleForward)
+		};
+		if (response.body !== null) {
+			const { readable, writable } = new TransformStream();
+			response.body.pipeTo(writable).finally(settleForward).catch(() => {});
+			return {
+				status: "response",
+				response: new Response(readable, response)
+			};
 		}
-		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") return await sandbox.fetch(switchPort(request, port));
-		let proxyUrl;
-		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,
-			"X-Forwarded-Proto": url.protocol.replace(":", ""),
-			"X-Sandbox-Name": sandboxId
+		settleForward();
+		return {
+			status: "response",
+			response
 		};
-		request.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		const proxyRequest = new Request(proxyUrl, {
-			method: request.method,
-			headers,
-			body: request.body,
-			duplex: "half",
-			redirect: "manual"
-		});
-		return await sandbox.containerFetch(proxyRequest, port);
 	} catch (error) {
-		logger.error("Proxy routing error", error instanceof Error ? error : new Error(String(error)));
-		return new Response("Proxy routing error", { status: 500 });
+		settleForward();
+		if (error instanceof Error && error.message.includes("Network connection lost.")) return { status: "network-lost" };
+		throw error;
 	}
 }
-function extractSandboxRoute(url) {
-	const dotIndex = url.hostname.indexOf(".");
-	if (dotIndex === -1) return null;
-	const subdomain = url.hostname.slice(0, dotIndex);
-	url.hostname.slice(dotIndex + 1);
-	const firstHyphen = subdomain.indexOf("-");
-	if (firstHyphen === -1) return null;
-	const portStr = subdomain.slice(0, firstHyphen);
-	if (!/^\d{4,5}$/.test(portStr)) return null;
-	const port = parseInt(portStr, 10);
-	if (!validatePort(port)) return null;
-	const rest = subdomain.slice(firstHyphen + 1);
-	const lastHyphen = rest.lastIndexOf("-");
-	if (lastHyphen === -1) return null;
-	const sandboxId = rest.slice(0, lastHyphen);
-	const token = rest.slice(lastHyphen + 1);
-	if (!/^[a-z0-9_]+$/.test(token) || token.length === 0 || token.length > 63) return null;
-	if (sandboxId.length === 0 || sandboxId.length > 63) return null;
-	let sanitizedSandboxId;
-	try {
-		sanitizedSandboxId = sanitizeSandboxId(sandboxId);
-	} catch {
-		return null;
+function bridgePreviewWebSocket(response, lifecycle, settleForward) {
+	const containerWebSocket = response.webSocket;
+	if (containerWebSocket === null) {
+		settleForward();
+		return response;
 	}
-	return {
-		port,
-		sandboxId: sanitizedSandboxId,
-		path: url.pathname || "/",
-		token
+	const [client, server] = Object.values(new WebSocketPair());
+	let settled = false;
+	const settle = () => {
+		if (!settled) {
+			settled = true;
+			settleForward();
+		}
 	};
+	containerWebSocket.accept();
+	server.accept();
+	server.addEventListener("message", async (event) => {
+		lifecycle.renewActivity();
+		try {
+			const data = event.data instanceof Blob ? await event.data.arrayBuffer() : event.data;
+			containerWebSocket.send(data);
+		} catch {
+			server.close(1011, "Failed to forward message to container");
+		}
+	});
+	containerWebSocket.addEventListener("message", async (event) => {
+		lifecycle.renewActivity();
+		try {
+			const data = event.data instanceof Blob ? await event.data.arrayBuffer() : event.data;
+			server.send(data);
+		} catch {
+			containerWebSocket.close(1011, "Failed to forward message to client");
+		}
+	});
+	server.addEventListener("close", (event) => {
+		settle();
+		const code = event.code === 1005 || event.code === 1006 ? 1e3 : event.code;
+		containerWebSocket.close(code, event.reason);
+	});
+	containerWebSocket.addEventListener("close", (event) => {
+		settle();
+		const code = event.code === 1005 || event.code === 1006 ? 1e3 : event.code;
+		server.close(code, event.reason);
+	});
+	server.addEventListener("error", () => {
+		settle();
+		containerWebSocket.close(1011, "Client WebSocket error");
+	});
+	containerWebSocket.addEventListener("error", () => {
+		settle();
+		server.close(1011, "Container WebSocket error");
+	});
+	return new Response(null, {
+		status: response.status,
+		webSocket: client,
+		headers: response.headers
+	});
 }
+
+//#endregion
+//#region src/preview-proxy-protocol.ts
+/** @internal */
+const PREVIEW_PROXY_HEADER = "x-sandbox-preview-proxy";
+/** @internal */
+const PREVIEW_PROXY_PORT_HEADER = "x-sandbox-preview-port";
+/** @internal */
+const PREVIEW_PROXY_TOKEN_HEADER = "x-sandbox-preview-token";
+/** @internal */
+const PREVIEW_PROXY_SANDBOX_ID_HEADER = "x-sandbox-preview-sandbox-id";
+/** @internal */
+const PREVIEW_PROXY_HEADERS = [
+	PREVIEW_PROXY_HEADER,
+	PREVIEW_PROXY_PORT_HEADER,
+	PREVIEW_PROXY_TOKEN_HEADER,
+	PREVIEW_PROXY_SANDBOX_ID_HEADER
+];
+
+//#endregion
+//#region src/preview-url.ts
 function isLocalhostPattern(hostname) {
-	if (hostname.startsWith("[")) if (hostname.includes("]:")) return hostname.substring(0, hostname.indexOf("]:") + 1) === "[::1]";
-	else return hostname === "[::1]";
+	if (hostname.startsWith("[")) {
+		if (hostname.includes("]:")) return hostname.substring(0, hostname.indexOf("]:") + 1) === "[::1]";
+		return hostname === "[::1]";
+	}
 	if (hostname === "::1") return true;
 	const hostPart = hostname.split(":")[0];
 	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
 }
 
+//#endregion
+//#region src/pty/proxy.ts
+async function proxyTerminal(stub, sessionId, request, options) {
+	if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId is required for terminal access");
+	if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") throw new Error("terminal() requires a WebSocket upgrade request");
+	const params = new URLSearchParams({ sessionId });
+	if (options?.cols) params.set("cols", String(options.cols));
+	if (options?.rows) params.set("rows", String(options.rows));
+	if (options?.shell) params.set("shell", options.shell);
+	const ptyUrl = `http://localhost/ws/pty?${params}`;
+	const ptyRequest = new Request(ptyUrl, request);
+	return stub.fetch(switchPort(ptyRequest, 3e3));
+}
+
 //#endregion
 //#region src/storage-mount/r2-egress-handler.ts
 const XML_NS = "xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"";
@@ -4652,6 +4775,178 @@ const r2EgressHandler = async (request, env$1, ctx) => {
 	}
 };
 
+//#endregion
+//#region src/tunnels/credentials.ts
+/**
+* Resolve a Cloudflare account id from environment with documented
+* precedence. Used by features that need to address a specific account
+* (Cloudflare Tunnel, R2 backup) to find their account id without
+* forcing every caller to set the same env var.
+*
+* Precedence (first non-empty wins):
+*   1. The feature-specific override env var (e.g. `CLOUDFLARE_TUNNEL_ACCOUNT_ID`).
+*   2. `CLOUDFLARE_ACCOUNT_ID`.
+*   3. The single account `CLOUDFLARE_API_TOKEN` is scoped to, via
+*      `GET /user/tokens/verify`. Multi-account tokens are rejected.
+*
+* The resolver is feature-agnostic; only the `overrideKey` differs per
+* caller. Throws on any failure with a message that names the env vars
+* the caller can set to fix it.
+*/
+const TOKEN_VERIFY_URL = "https://api.cloudflare.com/client/v4/user/tokens/verify";
+const ACCOUNTS_LIST_URL = "https://api.cloudflare.com/client/v4/accounts";
+/**
+* Per-request timeout for the credential introspection calls below.
+* Without one a hung Cloudflare control-plane call wedges every
+* first-time named-tunnel `get()` on the DO (the resolver promises are
+* memoised on `Sandbox`, so the first caller's hang is everyone's hang).
+*/
+const CREDENTIALS_TIMEOUT_MS = 1e4;
+/**
+* Fetch wrapper that adds an `AbortSignal.timeout` and surfaces a
+* timeout as a labelled `Error` so the caller can blame the right URL.
+*/
+async function fetchWithTimeout(fetcher, url, init, timeoutMs = CREDENTIALS_TIMEOUT_MS) {
+	try {
+		return await fetcher(url, {
+			...init,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (err) {
+		if (err instanceof Error && err.name === "TimeoutError") throw new Error(`Cloudflare API request to ${url} timed out after ${timeoutMs}ms`);
+		throw err;
+	}
+}
+/**
+* Cloudflare error code returned by `GET /user/tokens/verify` when the
+* presented token is an account-owned (`cfat-`) token rather than a
+* user-owned one. Matches the heuristic wrangler uses in
+* `src/user/whoami.ts` (`getTokenType`).
+*/
+const ACCOUNT_OWNED_TOKEN_CODE = 1e3;
+async function resolveAccountId(env$1, options) {
+	const override = getEnvString(env$1, options.overrideKey);
+	if (override) return override;
+	const generic = getEnvString(env$1, "CLOUDFLARE_ACCOUNT_ID");
+	if (generic) return generic;
+	const token = getEnvString(env$1, "CLOUDFLARE_API_TOKEN");
+	if (!token) throw new Error(`Cloudflare account id could not be resolved. Set one of: ${options.overrideKey}, CLOUDFLARE_ACCOUNT_ID, or CLOUDFLARE_API_TOKEN (a token scoped to a single account).`);
+	const fetcher = options.fetcher ?? fetch;
+	const response = await fetchWithTimeout(fetcher, TOKEN_VERIFY_URL, {
+		method: "GET",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		}
+	});
+	let body;
+	try {
+		body = await response.json();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cloudflare token verification returned malformed JSON: ${message}`);
+	}
+	if (response.ok && body?.success) {
+		const derived = body.result_info?.account?.id;
+		if (!derived) throw new Error(`Cloudflare token is not scoped to a single account (ambiguous). Set ${options.overrideKey} or CLOUDFLARE_ACCOUNT_ID explicitly.`);
+		return derived;
+	}
+	if (body?.errors?.some((e) => e.code === ACCOUNT_OWNED_TOKEN_CODE)) return await deriveAccountIdViaAccountToken(token, fetcher, options);
+	throw new Error(`Cloudflare token verification failed with status ${response.status}. Check that CLOUDFLARE_API_TOKEN is valid or set ${options.overrideKey} / CLOUDFLARE_ACCOUNT_ID explicitly.`);
+}
+/**
+* Account-owned token (cfat-) fallback: list the accounts the token can
+* see, and — if there's exactly one — confirm with the account-scoped
+* verify endpoint before returning the id.
+*
+* Common failure modes get specific, actionable error messages:
+*   - `/accounts` 403 (token lacks `account:read`): tell the caller to
+*     set `CLOUDFLARE_ACCOUNT_ID` explicitly.
+*   - multiple accounts: same.
+*   - zero accounts: same.
+*   - confirm step fails: surface the API error code verbatim.
+*/
+async function deriveAccountIdViaAccountToken(token, fetcher, options) {
+	const listResponse = await fetchWithTimeout(fetcher, `${ACCOUNTS_LIST_URL}?per_page=2`, {
+		method: "GET",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		}
+	});
+	let listBody;
+	try {
+		listBody = await listResponse.json();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cloudflare account-owned token: /accounts returned malformed JSON: ${message}`);
+	}
+	if (!listResponse.ok || !listBody?.success) throw new Error(`Cloudflare account-owned token (cfat-...) detected, but /accounts returned status ${listResponse.status}. The token may lack account:read scope. Set CLOUDFLARE_ACCOUNT_ID explicitly to skip introspection.`);
+	const accounts = listBody.result ?? [];
+	if (accounts.length === 0) throw new Error("Cloudflare account-owned token has access to no accounts. Set CLOUDFLARE_ACCOUNT_ID explicitly.");
+	if (accounts.length > 1) throw new Error("Cloudflare account-owned token has access to multiple accounts (ambiguous). Set CLOUDFLARE_ACCOUNT_ID explicitly to disambiguate.");
+	const accountId = accounts[0]?.id;
+	if (!accountId) throw new Error("Cloudflare /accounts returned a result without an id field.");
+	const verifyResponse = await fetchWithTimeout(fetcher, `${ACCOUNTS_LIST_URL}/${encodeURIComponent(accountId)}/tokens/verify`, {
+		method: "GET",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		}
+	});
+	let verifyBody;
+	try {
+		verifyBody = await verifyResponse.json();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cloudflare account token verify returned malformed JSON: ${message}`);
+	}
+	if (!verifyResponse.ok || !verifyBody?.success) {
+		const detail = verifyBody?.errors?.map((e) => `${e.code}: ${e.message}`).join("; ") ?? `HTTP ${verifyResponse.status}`;
+		throw new Error(`Cloudflare account token verify failed for account ${accountId}: ${detail}`);
+	}
+	return accountId;
+}
+const ZONES_LIST_URL = "https://api.cloudflare.com/client/v4/zones";
+/**
+* Resolve a Cloudflare zone id.
+*
+* Precedence:
+*   1. `CLOUDFLARE_ZONE_ID` env var.
+*   2. The single zone the token can see under `accountId`, via
+*      `GET /zones?account.id=<accountId>&per_page=2`.
+*
+* Step 2 deliberately fetches at most two results: one is the happy path,
+* two (or more) means the token is ambiguous and we refuse to guess.
+* Multi-zone tokens must set `CLOUDFLARE_ZONE_ID` explicitly so the
+* caller's intent is unambiguous.
+*/
+async function resolveZoneId(env$1, options) {
+	const envZone = getEnvString(env$1, "CLOUDFLARE_ZONE_ID");
+	if (envZone) return envZone;
+	const response = await fetchWithTimeout(options.fetcher ?? fetch, `${ZONES_LIST_URL}?account.id=${encodeURIComponent(options.accountId)}&per_page=2`, {
+		method: "GET",
+		headers: {
+			authorization: `Bearer ${options.token}`,
+			"content-type": "application/json"
+		}
+	});
+	if (!response.ok) throw new Error(`Cloudflare zones lookup failed with status ${response.status}. Set CLOUDFLARE_ZONE_ID explicitly or grant the API token Zone:Read.`);
+	let body;
+	try {
+		body = await response.json();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cloudflare zones lookup returned malformed JSON: ${message}`);
+	}
+	const zones = body.result ?? [];
+	if (zones.length === 0) throw new Error(`Cloudflare API token has access to no zones in account ${options.accountId}. Set CLOUDFLARE_ZONE_ID explicitly or grant the token Zone:Read on the intended zone.`);
+	if (zones.length > 1) throw new Error(`Cloudflare API token has access to multiple zones in account ${options.accountId} (ambiguous). Set CLOUDFLARE_ZONE_ID explicitly to disambiguate.`);
+	const zoneId = zones[0]?.id;
+	if (!zoneId) throw new Error("Cloudflare zones lookup returned a result without an id field.");
+	return zoneId;
+}
+
 //#endregion
 //#region src/tunnels/sandbox-control-callback.ts
 var SandboxControlCallbackImpl = class extends RpcTarget {
@@ -4674,6 +4969,229 @@ var SandboxControlCallbackImpl = class extends RpcTarget {
 	}
 };
 
+//#endregion
+//#region src/tunnels/cloudflare-api.ts
+/**
+* Cloudflare API client for named-tunnel orchestration.
+*
+* Design notes:
+*
+* - The Cloudflare API envelope is `{ success, result, errors }`. We
+*   unwrap `result` on success and surface a thrown `Error` with the
+*   API error code/message on failure. Transport-level errors
+*   propagate unchanged.
+* - Delete endpoints are idempotent from the caller's perspective:
+*   a 404 (already gone) resolves successfully so destroy() can run
+*   without special-casing.
+* - `upsertCNAME` is the most subtle wrapper: it lists existing
+*   records, reuses a matching one, and refuses to mutate a record
+*   whose content differs from what we want. This is the fence that
+*   stops two sandboxes from racing on the same hostname.
+*/
+const API_BASE = "https://api.cloudflare.com/client/v4";
+/**
+* Default request timeout. Cloudflare API P99 latency is well under
+* this; values much smaller risk false positives on cold control-plane
+* paths (e.g. first `cfd_tunnel` POST in a new account).
+*/
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* Internal request helper. Centralises auth header, JSON encoding,
+* timeout enforcement, and envelope unwrapping so each wrapper above
+* stays declarative.
+*/
+async function cfRequest(url, token, fetcher, options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const init = {
+		method: options.method ?? "GET",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		signal: AbortSignal.timeout(timeoutMs)
+	};
+	if (options.body !== void 0) init.body = JSON.stringify(options.body);
+	let response;
+	try {
+		response = await fetcher(url, init);
+	} catch (err) {
+		if (err instanceof Error && err.name === "TimeoutError") throw new Error(`Cloudflare API request to ${url} timed out after ${timeoutMs}ms`);
+		throw err;
+	}
+	if (options.acceptStatuses?.includes(response.status)) return;
+	let envelope;
+	try {
+		envelope = await response.json();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cloudflare API returned non-JSON response (status ${response.status}): ${message}`);
+	}
+	if (!response.ok || envelope.success === false) {
+		const errs = envelope.errors ?? [];
+		const summary = errs.length ? errs.map((e) => `${e.code ?? "???"}: ${e.message ?? "unknown"}`).join(", ") : `HTTP ${response.status}`;
+		throw new Error(`Cloudflare API error: ${summary}`);
+	}
+	return envelope.result;
+}
+/**
+* Heuristic for the "tags are an Enterprise-only feature" error class.
+* Empirically grounded against a non-Enterprise account:
+*
+*   - DNS create with `tags: [...]` on a non-Enterprise zone rejects with
+*     Cloudflare error code 9300 and the message "DNS record has N tags,
+*     exceeding the quota of 0.". The error string `cfRequest` constructs
+*     embeds both the code and the message, so we match on either signal.
+*   - Tunnel create with `tags: [...]` silently succeeds and drops the
+*     field on the floor (no error to retry on). The fallback wrapper
+*     therefore costs nothing on tunnel writes.
+*
+* Generic "requires Enterprise" phrasing is also matched as a forward-
+* compatibility hedge in case Cloudflare changes the response shape on
+* future endpoints.
+*/
+function isEnterpriseOnlyTagError(error) {
+	if (!(error instanceof Error)) return false;
+	const msg = error.message.toLowerCase();
+	if (msg.includes("9300") && msg.includes("tag")) return true;
+	if (!msg.includes("tag")) return false;
+	return msg.includes("quota") || msg.includes("enterprise") || msg.includes("not allowed") || msg.includes("not entitled") || msg.includes("not available") || msg.includes("not supported");
+}
+/**
+* Build the `tags` field attached to created Cloudflare resources. The
+* tag is `sandboxId:<id>`, the same key used in DNS comments / tunnel
+* metadata; together they let an operator find every resource a given
+* sandbox owns from the Cloudflare dashboard.
+*
+* Tags are an Enterprise-only feature. The wrapper `createWithTagFallback`
+* automatically retries the request without tags on the documented
+* "requires Enterprise" error so non-enterprise accounts succeed without
+* any configuration.
+*/
+function buildSandboxTags(sandboxId) {
+	if (!sandboxId) return void 0;
+	return [`sandboxId:${sandboxId}`];
+}
+/**
+* Wrap a tagged-create request with an automatic tag-strip retry. The
+* callback receives `tags`: pass it through to the request body as-is on
+* the first call (`undefined` on the retry). The retry only fires for
+* the Enterprise-only tag error class; any other failure surfaces
+* verbatim.
+*/
+async function createWithTagFallback(sandboxId, send) {
+	const tags = buildSandboxTags(sandboxId);
+	if (!tags) return send(void 0);
+	try {
+		return await send(tags);
+	} catch (err) {
+		if (!isEnterpriseOnlyTagError(err)) throw err;
+		return send(void 0);
+	}
+}
+async function createTunnel(args) {
+	const fetcher = args.fetcher ?? fetch;
+	const result = await createWithTagFallback(args.metadata.sandboxId, (tags) => cfRequest(`${API_BASE}/accounts/${encodeURIComponent(args.accountId)}/cfd_tunnel`, args.token, fetcher, {
+		method: "POST",
+		body: {
+			name: args.tunnelName,
+			config_src: "cloudflare",
+			metadata: args.metadata,
+			...tags ? { tags } : {}
+		}
+	}));
+	if (!result) throw new Error("Cloudflare tunnel create returned no result body");
+	return {
+		id: result.id,
+		token: result.token
+	};
+}
+/**
+* Look up an existing tunnel by exact name match. Filters out tunnels
+* marked `deleted_at != null` defensively in case the API ignores the
+* `is_deleted=false` query parameter.
+*
+* When `expectedSandboxId` is provided, also verify that the tunnel's
+* `metadata.sandboxId` tag matches — this is the authoritative "this
+* resource was created by this sandbox" check, and the tag is set by
+* `createTunnel`. Mismatches are treated as "not found" so the caller
+* falls through to creating a fresh tunnel.
+*/
+async function findTunnelByName(args) {
+	const fetcher = args.fetcher ?? fetch;
+	const result = await cfRequest(`${API_BASE}/accounts/${encodeURIComponent(args.accountId)}/cfd_tunnel?name=${encodeURIComponent(args.tunnelName)}&is_deleted=false`, args.token, fetcher);
+	if (!result) return null;
+	const live = result.find((t) => !t.deleted_at);
+	if (!live) return null;
+	if (args.expectedSandboxId !== void 0) {
+		if (live.metadata?.sandboxId !== args.expectedSandboxId) return null;
+	}
+	return {
+		id: live.id,
+		name: live.name
+	};
+}
+async function deleteTunnel(args) {
+	const fetcher = args.fetcher ?? fetch;
+	await cfRequest(`${API_BASE}/accounts/${encodeURIComponent(args.accountId)}/cfd_tunnel/${encodeURIComponent(args.tunnelId)}`, args.token, fetcher, {
+		method: "DELETE",
+		acceptStatuses: [404]
+	});
+}
+/**
+* Fetch the opaque `--token` for an existing tunnel. Used on the retry
+* path: when `findTunnelByName` discovers a tunnel left behind from a
+* previous failed attempt, we need its token to run `cloudflared` again.
+*
+* The Cloudflare API returns the token as a bare quoted string in the
+* `result` envelope (e.g. `"<base64-token>"`).
+*/
+async function getTunnelToken(args) {
+	const fetcher = args.fetcher ?? fetch;
+	const result = await cfRequest(`${API_BASE}/accounts/${encodeURIComponent(args.accountId)}/cfd_tunnel/${encodeURIComponent(args.tunnelId)}/token`, args.token, fetcher);
+	if (typeof result !== "string" || result.length === 0) throw new Error(`Cloudflare did not return a token for tunnel ${args.tunnelId}`);
+	return result;
+}
+async function getZoneName(args) {
+	const fetcher = args.fetcher ?? fetch;
+	const result = await cfRequest(`${API_BASE}/zones/${encodeURIComponent(args.zoneId)}`, args.token, fetcher);
+	if (!result?.name) throw new Error(`Cloudflare zone ${args.zoneId} did not return a name`);
+	return result.name;
+}
+async function upsertCNAME(args) {
+	const fetcher = args.fetcher ?? fetch;
+	const existing = (await cfRequest(`${API_BASE}/zones/${encodeURIComponent(args.zoneId)}/dns_records?type=CNAME&name=${encodeURIComponent(args.hostname)}`, args.token, fetcher) ?? []).find((r) => r.type === "CNAME" && r.name === args.hostname);
+	if (existing) {
+		if (existing.content === args.cnameTarget) return {
+			recordId: existing.id,
+			reused: true
+		};
+		throw new Error(`DNS record for ${args.hostname} already exists with different content (owned by you, not us): existing content="${existing.content}", existing comment="${existing.comment ?? ""}". Delete the record manually to allow the sandbox to manage it.`);
+	}
+	const createResult = await createWithTagFallback(args.sandboxId, (tags) => cfRequest(`${API_BASE}/zones/${encodeURIComponent(args.zoneId)}/dns_records`, args.token, fetcher, {
+		method: "POST",
+		body: {
+			type: "CNAME",
+			name: args.hostname,
+			content: args.cnameTarget,
+			proxied: true,
+			comment: args.comment,
+			...tags ? { tags } : {}
+		}
+	}));
+	if (!createResult) throw new Error("Cloudflare DNS create returned no result body");
+	return {
+		recordId: createResult.id,
+		reused: false
+	};
+}
+async function deleteDNSRecord(args) {
+	const fetcher = args.fetcher ?? fetch;
+	await cfRequest(`${API_BASE}/zones/${encodeURIComponent(args.zoneId)}/dns_records/${encodeURIComponent(args.recordId)}`, args.token, fetcher, {
+		method: "DELETE",
+		acceptStatuses: [404]
+	});
+}
+
 //#endregion
 //#region src/tunnels/tunnels-handler.ts
 /**
@@ -4688,6 +5206,14 @@ var SandboxControlCallbackImpl = class extends RpcTarget {
 */
 /** DO storage key for the `port → TunnelInfo` map. */
 const STORAGE_KEY = "tunnels";
+/**
+* Sidecar storage key for per-port metadata the handler needs but the
+* public `TunnelInfo` shape does not carry: the options hash used to
+* detect divergent retries, and (for named tunnels) the DNS record id
+* needed for cleanup. Kept under a separate key so the existing
+* `tunnels` shape remains a clean `Record<port, TunnelInfo>`.
+*/
+const META_STORAGE_KEY = "tunnels:meta";
 function validateTunnelPort(port) {
 	if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding reserved ports.`);
 }
@@ -4697,47 +5223,142 @@ function shortId() {
 	crypto.getRandomValues(buf);
 	return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+/**
+* Match a structured SandboxError code anywhere on the error — translated
+* SandboxErrors expose the code both as a top-level `code` field and on
+* the nested `errorResponse.code`. Used for the few error codes the SDK
+* recognises and recovers from (TUNNEL_NOT_FOUND, TUNNEL_ALREADY_RUNNING).
+*
+* Previous versions matched by substring on `error.message`, which
+* false-positived on any error whose message merely quoted the literal
+* code token.
+*/
+function hasErrorCode(error, code) {
+	if (!error || typeof error !== "object") return false;
+	const e = error;
+	if (e.code === code) return true;
+	if (e.errorResponse?.code === code) return true;
+	return false;
+}
 function isTunnelNotFoundError(error) {
-	return (error instanceof Error ? error.message : String(error)).includes("TUNNEL_NOT_FOUND");
+	return hasErrorCode(error, "TUNNEL_NOT_FOUND");
+}
+function isTunnelAlreadyRunningError(error) {
+	return hasErrorCode(error, "TUNNEL_ALREADY_RUNNING");
 }
 async function readMap(storage) {
 	return await storage.get(STORAGE_KEY) ?? {};
 }
+async function readMetaMap(storage) {
+	return await storage.get(META_STORAGE_KEY) ?? {};
+}
 /**
-* Concrete `TunnelsHandler` implementation. Extends `RpcTarget` so it
-* can cross the Workers RPC boundary: the Sandbox DO is reachable from
-* Workers via Workers RPC (`stub.tunnels.get(port)`), and only
-* `RpcTarget` instances are passed by reference across that boundary.
+* Stable hash of `options`. Empty/undefined options collapse to the same
+* hash so `get(port)`, `get(port, {})`, and `get(port, { name: undefined })`
+* all hit the same cache entry. Named tunnels hash on `name` alone (the
+* only option today).
+*
+* The `v1:` prefix exists so a future addition of a second option (e.g.
+* `subdomain`) can change the canonical form without colliding with an
+* older record's hash. Comparison goes through `optionsHashesEqual`, which
+* normalises legacy unversioned hashes (`quick`, `named:foo`) to their v1
+* form before equality, so upgrading does not invalidate cached records.
+*/
+function computeOptionsHash(options) {
+	if (!options || !options.name) return "v1:quick";
+	return `v1:named:${options.name}`;
+}
+/** Strip the optional `v1:` prefix so legacy hashes compare equal. */
+function normaliseHash(hash) {
+	return hash.startsWith("v1:") ? hash.slice(3) : hash;
+}
+function optionsHashesEqual(a, b) {
+	return normaliseHash(a) === normaliseHash(b);
+}
+/**
+* Concrete `TunnelsHandler` implementation.
+*
+* Extends `RpcTarget` for forward compatibility with direct Workers RPC
+* pipelining (`stub.tunnels.get(port)`): only `RpcTarget` instances may
+* be passed by reference across the Workers RPC boundary. Today the
+* public `sandbox.tunnels` proxy in `getSandbox()` dispatches through
+* `stub.callTunnels(method, args)` instead — pipelining through
+* property getters is broken under the vite-plugin runtime — so the
+* `RpcTarget` base is not on the hot call path. It is retained so the
+* pipelining shape works once that constraint lifts.
 */
 var TunnelsRpcTarget = class extends RpcTarget$1 {
 	#host;
 	#withPortLock;
+	/**
+	* Memoised zone name (e.g. `'example.com'`) for the configured
+	* `CLOUDFLARE_ZONE_ID`. Filled in lazily on the first named-tunnel
+	* `get()` so quick-tunnel callers never hit the zone-lookup endpoint.
+	*
+	* Only successful resolutions are cached: a rejected lookup clears
+	* the slot so the next caller retries, instead of permanently
+	* poisoning every subsequent named-tunnel `get()` on the DO with the
+	* same transient error.
+	*/
+	#zoneNamePromise = null;
 	constructor(host, withPortLock) {
 		super();
 		this.#host = host;
 		this.#withPortLock = withPortLock;
 	}
-	async get(port) {
+	/**
+	* Resolve the zone name for the configured zone id. Memoised for the
+	* lifetime of this handler; the zone name doesn't change while a DO
+	* is alive, and one extra GET on first use is cheaper than threading
+	* the value through the host.
+	*
+	* On failure the cached promise is cleared so the next caller retries.
+	* Without that, a transient 5xx on the first call would permanently
+	* poison every subsequent named-tunnel `get()` until the DO restarts.
+	*/
+	async #getZoneName(config) {
+		if (!this.#zoneNamePromise) {
+			const pending = getZoneName({
+				token: config.token,
+				zoneId: config.zoneId,
+				fetcher: this.#host.fetcher
+			});
+			this.#zoneNamePromise = pending;
+			pending.catch(() => {
+				if (this.#zoneNamePromise === pending) this.#zoneNamePromise = null;
+			});
+		}
+		return this.#zoneNamePromise;
+	}
+	async get(port, options) {
 		const startTime = Date.now();
 		let outcome = "error";
 		let cacheState = "miss";
 		let caughtError;
 		try {
 			validateTunnelPort(port);
+			if (options?.name !== void 0) validateTunnelName(options.name);
+			const requestedHash = computeOptionsHash(options);
 			const info = await this.#withPortLock(port, async () => {
 				const existing = (await readMap(this.#host.storage))[port.toString()];
 				if (existing) {
+					const metaEntry = (await readMetaMap(this.#host.storage))[port.toString()];
+					if (!optionsHashesEqual(metaEntry?.optionsHash ?? (existing.name ? `v1:named:${existing.name}` : "v1:quick"), requestedHash)) throw new Error(`Tunnel on port ${port} was created with different options. Call destroy(${port}) before changing tunnel options.`);
+					if (metaEntry?.needsRespawn && existing.name) return await this.#provisionNamedTunnel(port, existing.name);
+					if (existing.name && this.#host.getNamedTunnelConfig) {
+						const currentConfig = await this.#host.getNamedTunnelConfig();
+						const storedAccountId = metaEntry?.accountId;
+						const storedZoneId = metaEntry?.zoneId;
+						if (storedAccountId !== void 0 && storedAccountId !== currentConfig.accountId || storedZoneId !== void 0 && storedZoneId !== currentConfig.zoneId) {
+							this.#zoneNamePromise = null;
+							return await this.#provisionNamedTunnel(port, existing.name);
+						}
+					}
 					cacheState = "hit";
 					return existing;
 				}
-				const id = `quick-${shortId()}`;
-				const spawned = await this.#host.client.tunnels.runQuickTunnel(id, port);
-				await this.#host.storage.transaction(async (txn) => {
-					const nextMap = await readMap(txn);
-					nextMap[port.toString()] = spawned;
-					await txn.put(STORAGE_KEY, nextMap);
-				});
-				return spawned;
+				if (options?.name) return await this.#provisionNamedTunnel(port, options.name);
+				return await this.#provisionQuickTunnel(port);
 			});
 			outcome = "success";
 			return info;
@@ -4755,6 +5376,129 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 			});
 		}
 	}
+	/**
+	* Provision a fresh quick tunnel and persist it. Caller holds the
+	* per-port lock.
+	*
+	* Quick-tunnel ids are minted from a 32-bit random source. Collisions
+	* are astronomically unlikely, but if the container happens to already
+	* have one running under the freshly-minted id it rejects with
+	* TUNNEL_ALREADY_RUNNING. Mint a fresh id and try again rather than
+	* surfacing the confusing error — the retry budget caps the loop so a
+	* persistent failure still surfaces.
+	*/
+	async #provisionQuickTunnel(port) {
+		const MAX_ID_RETRIES = 3;
+		let lastError;
+		for (let attempt = 0; attempt < MAX_ID_RETRIES; attempt += 1) {
+			const id = `quick-${shortId()}`;
+			try {
+				const spawned = await this.#host.client.tunnels.runQuickTunnel(id, port);
+				await this.#host.storage.transaction(async (txn) => {
+					const nextMap = await readMap(txn);
+					nextMap[port.toString()] = spawned;
+					await txn.put(STORAGE_KEY, nextMap);
+					const nextMeta = await readMetaMap(txn);
+					nextMeta[port.toString()] = { optionsHash: "v1:quick" };
+					await txn.put(META_STORAGE_KEY, nextMeta);
+				});
+				return spawned;
+			} catch (err) {
+				if (!isTunnelAlreadyRunningError(err)) throw err;
+				lastError = err;
+			}
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("Failed to mint a unique quick-tunnel id");
+	}
+	/**
+	* Provision a named tunnel end-to-end:
+	*   1. resolve credentials + zone name
+	*   2. reuse or create the Cloudflare tunnel resource
+	*   3. upsert the proxied CNAME (or reuse a matching one)
+	*   4. spawn cloudflared inside the container
+	*   5. persist the record + meta
+	*
+	* Failure between (2) and (5) intentionally leaves the Cloudflare-side
+	* resources in place so a retry can re-discover them via
+	* `findTunnelByName` and the DNS reuse path. See
+	* `.plans/09-named-tunnel-api.md § Retry-friendly failure model`.
+	*/
+	async #provisionNamedTunnel(port, name) {
+		if (!this.#host.sandboxId) throw new Error("Named tunnels require host.sandboxId on the tunnels handler.");
+		if (!this.#host.getNamedTunnelConfig) throw new Error("Named tunnels require host.getNamedTunnelConfig on the tunnels handler.");
+		const config = await this.#host.getNamedTunnelConfig();
+		const hostname = `${name}.${await this.#getZoneName({
+			token: config.token,
+			zoneId: config.zoneId
+		})}`;
+		const sandboxId = this.#host.sandboxId;
+		const tunnelName = `sandbox-${sandboxId}-${name}`;
+		let tunnelId;
+		let tunnelToken;
+		const existingTunnel = await findTunnelByName({
+			token: config.token,
+			accountId: config.accountId,
+			tunnelName,
+			expectedSandboxId: sandboxId,
+			fetcher: this.#host.fetcher
+		});
+		if (existingTunnel) {
+			tunnelId = existingTunnel.id;
+			tunnelToken = await getTunnelToken({
+				token: config.token,
+				accountId: config.accountId,
+				tunnelId,
+				fetcher: this.#host.fetcher
+			});
+		} else {
+			const created = await createTunnel({
+				token: config.token,
+				accountId: config.accountId,
+				tunnelName,
+				metadata: {
+					sandboxId,
+					createdBy: "sandbox-sdk",
+					name,
+					port
+				},
+				fetcher: this.#host.fetcher
+			});
+			tunnelId = created.id;
+			tunnelToken = created.token;
+		}
+		const dnsResult = await upsertCNAME({
+			token: config.token,
+			zoneId: config.zoneId,
+			hostname,
+			cnameTarget: `${tunnelId}.cfargotunnel.com`,
+			comment: `sandbox-${sandboxId}`,
+			sandboxId,
+			fetcher: this.#host.fetcher
+		});
+		await this.#host.client.tunnels.runNamedTunnel(tunnelId, tunnelToken, port);
+		const info = {
+			id: tunnelId,
+			port,
+			name,
+			hostname,
+			url: `https://${hostname}`,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.#host.storage.transaction(async (txn) => {
+			const nextMap = await readMap(txn);
+			nextMap[port.toString()] = info;
+			await txn.put(STORAGE_KEY, nextMap);
+			const nextMeta = await readMetaMap(txn);
+			nextMeta[port.toString()] = {
+				optionsHash: computeOptionsHash({ name }),
+				dnsRecordId: dnsResult.recordId,
+				accountId: config.accountId,
+				zoneId: config.zoneId
+			};
+			await txn.put(META_STORAGE_KEY, nextMeta);
+		});
+		return info;
+	}
 	async destroy(portOrInfo) {
 		const port = typeof portOrInfo === "number" ? portOrInfo : portOrInfo.port;
 		const startTime = Date.now();
@@ -4766,16 +5510,68 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 				const existing = (await readMap(this.#host.storage))[port.toString()];
 				if (!existing) return;
 				tunnelId = existing.id;
+				const metaBefore = (await readMetaMap(this.#host.storage))[port.toString()];
 				await this.#host.storage.transaction(async (txn) => {
 					const current = await readMap(txn);
 					delete current[port.toString()];
 					await txn.put(STORAGE_KEY, current);
+					const currentMeta = await readMetaMap(txn);
+					delete currentMeta[port.toString()];
+					await txn.put(META_STORAGE_KEY, currentMeta);
 				});
 				try {
 					await this.#host.client.tunnels.destroyTunnel(existing.id);
 				} catch (error) {
-					if (!isTunnelNotFoundError(error)) throw error;
+					if (isTunnelNotFoundError(error)) {} else if (metaBefore?.dnsRecordId) this.#host.logger.warn("tunnel.destroy: container tunnel cleanup failed", {
+						port,
+						tunnelId,
+						error: error instanceof Error ? error.message : String(error)
+					});
+					else throw error;
 				}
+				if (!metaBefore?.dnsRecordId) return;
+				if (!this.#host.getNamedTunnelConfig) return;
+				let config;
+				try {
+					config = await this.#host.getNamedTunnelConfig();
+				} catch (err) {
+					this.#host.logger.warn("tunnel.destroy: skipping CF cleanup, credentials unavailable", {
+						port,
+						tunnelId,
+						dnsRecordId: metaBefore.dnsRecordId,
+						error: err instanceof Error ? err.message : String(err)
+					});
+					return;
+				}
+				const fetcher = this.#host.fetcher;
+				const accountId = metaBefore.accountId ?? config.accountId;
+				const zoneId = metaBefore.zoneId ?? config.zoneId;
+				await Promise.allSettled([metaBefore.dnsRecordId ? deleteDNSRecord({
+					token: config.token,
+					zoneId,
+					recordId: metaBefore.dnsRecordId,
+					fetcher
+				}).catch((err) => {
+					this.#host.logger.warn("tunnel.destroy: dns delete failed", {
+						port,
+						tunnelId,
+						recordId: metaBefore.dnsRecordId,
+						zoneId,
+						error: err instanceof Error ? err.message : String(err)
+					});
+				}) : Promise.resolve(), deleteTunnel({
+					token: config.token,
+					accountId,
+					tunnelId: existing.id,
+					fetcher
+				}).catch((err) => {
+					this.#host.logger.warn("tunnel.destroy: tunnel delete failed", {
+						port,
+						tunnelId,
+						accountId,
+						error: err instanceof Error ? err.message : String(err)
+					});
+				})]);
 			});
 			outcome = "success";
 		} catch (error) {
@@ -4807,29 +5603,126 @@ function createTunnelsHandler(host) {
 	const tunnels = new TunnelsRpcTarget(host, withPortLock);
 	const handleTunnelExit = async (id, port, exitCode) => {
 		const startTime = Date.now();
-		await withPortLock(port, async () => {
-			await host.storage.transaction(async (txn) => {
-				const map = await readMap(txn);
-				if (map[port.toString()]?.id === id) {
+		let outcome = "error";
+		let caughtError;
+		try {
+			await withPortLock(port, async () => {
+				await host.storage.transaction(async (txn) => {
+					const map = await readMap(txn);
+					const existing = map[port.toString()];
+					if (existing?.id !== id) return;
+					if (existing.name) {
+						const meta$1 = await readMetaMap(txn);
+						meta$1[port.toString()] = {
+							...meta$1[port.toString()],
+							optionsHash: meta$1[port.toString()]?.optionsHash ?? `v1:named:${existing.name}`,
+							needsRespawn: true
+						};
+						await txn.put(META_STORAGE_KEY, meta$1);
+						return;
+					}
 					delete map[port.toString()];
 					await txn.put(STORAGE_KEY, map);
-				}
+					const meta = await readMetaMap(txn);
+					delete meta[port.toString()];
+					await txn.put(META_STORAGE_KEY, meta);
+				});
 			});
+			outcome = "success";
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
 			logCanonicalEvent(host.logger, {
 				event: "tunnel.exit",
-				outcome: "success",
+				outcome,
 				port,
 				tunnelId: id,
 				exitCode: exitCode ?? void 0,
-				durationMs: Date.now() - startTime
+				durationMs: Date.now() - startTime,
+				error: caughtError
 			});
-		});
+		}
+	};
+	/**
+	* Iterate every stored tunnel and call `tunnels.destroy(port)` on it,
+	* sequentially. Each `destroy()` already swallows container-side
+	* TUNNEL_NOT_FOUND and best-effort-logs Cloudflare-side failures; we
+	* wrap the call in catch-and-log here too so a transport-level error
+	* on one port can't poison the rest of the teardown.
+	*
+	* Each port is processed sequentially: this caps the *number of
+	* concurrent ports* in flight at one. Note that an individual
+	* destroy() still fans the DNS-delete and tunnel-delete out via
+	* `Promise.allSettled` internally — so "sequential" here means
+	* "one port at a time", not "one Cloudflare API call at a time".
+	* The handful of ports we expect in the common case makes the
+	* trade-off cheap.
+	*/
+	const destroyAll = async () => {
+		const map = await readMap(host.storage);
+		const ports = Object.keys(map).map((p) => Number(p));
+		for (const port of ports) try {
+			await tunnels.destroy(port);
+		} catch (err) {
+			host.logger.warn("tunnels.destroyAll: destroy(port) failed", {
+				port,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
 	};
 	return {
 		tunnels,
-		handleTunnelExit
+		handleTunnelExit,
+		destroyAll
 	};
 }
+/**
+* Reconcile storage with a fresh container.
+*
+* Called from `Sandbox.onStart()` after every container restart. The
+* `cloudflared` processes the container was running all died with it, so
+* any stored record is *not* currently backed by a running tunnel.
+*
+* Two tunnel flavours, two recovery stories:
+*
+*   - Quick tunnels: the `*.trycloudflare.com` URL is bound to the dead
+*     `cloudflared` process. Nothing on Cloudflare's side outlives the
+*     container, and the URL is unrecoverable. Drop the record from both
+*     maps so the next `get(port)` takes the miss branch and mints a new
+*     URL.
+*   - Named tunnels: the Cloudflare-side tunnel + DNS record survive.
+*     The hostname is stable, the DNS still resolves to
+*     `<tunnelId>.cfargotunnel.com`, and the next caller can reuse both
+*     by walking the same `findTunnelByName` / `upsertCNAME` path the
+*     SDK uses for retries. Keep the record in storage and mark the
+*     meta entry `needsRespawn: true`; the next `get(port, { name })`
+*     cache hit falls through to `#provisionNamedTunnel` to respawn
+*     `cloudflared`.
+*
+* Crucially, named-tunnel metadata (including `dnsRecordId`) is
+* preserved so `destroy(port)` and `sandbox.destroy()` can still clean
+* up the Cloudflare-side resources after a restart. Wiping meta
+* unconditionally — the previous behaviour — silently leaked the tunnel
+* and DNS record on every restart.
+*/
+async function pruneTunnelsForRestart(storage) {
+	await storage.transaction(async (txn) => {
+		const map = await readMap(txn);
+		const meta = await readMetaMap(txn);
+		const nextMap = {};
+		const nextMeta = {};
+		for (const [portKey, info] of Object.entries(map)) if (info.name) {
+			nextMap[portKey] = info;
+			nextMeta[portKey] = {
+				...meta[portKey] ?? { optionsHash: `v1:named:${info.name}` },
+				needsRespawn: true
+			};
+		}
+		await txn.put(STORAGE_KEY, nextMap);
+		await txn.put(META_STORAGE_KEY, nextMeta);
+	});
+}
 
 //#endregion
 //#region src/version.ts
@@ -4838,10 +5731,12 @@ function createTunnelsHandler(host) {
 * 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.10.2";
+const SDK_VERSION = "0.11.0";
 
 //#endregion
 //#region src/sandbox.ts
+const PORT_TOKENS_STORAGE_KEY = "portTokens";
+const ACTIVE_PREVIEW_PORTS_STORAGE_KEY = "activePreviewPorts";
 const R2_EGRESS_PROXY_TARGET_CLASS_NAME = "CloudflareSandboxR2EgressProxyTarget";
 var R2EgressProxyTarget = class extends Container {};
 Object.defineProperty(R2EgressProxyTarget, "name", { value: R2_EGRESS_PROXY_TARGET_CLASS_NAME });
@@ -4987,14 +5882,63 @@ function getSandbox(ns, id, options) {
 		});
 	}
 	const defaultSessionId = `sandbox-${effectiveId}`;
+	const useDefaultSession = options?.enableDefaultSession !== false;
 	const enhancedMethods = {
 		fetch: (request) => stub.fetch(request),
+		exec: (command, execOptions) => useDefaultSession ? stub.exec(command, execOptions) : stub.execWithSessionToken(command, DISABLE_SESSION_TOKEN, execOptions),
+		startProcess: (command, processOptions) => useDefaultSession || processOptions?.sessionId !== void 0 ? stub.startProcess(command, processOptions) : stub.startProcess(command, {
+			...processOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		listProcesses: (sessionId) => useDefaultSession || sessionId !== void 0 ? stub.listProcesses(sessionId) : stub.listProcesses(DISABLE_SESSION_TOKEN),
+		getProcess: (id$1, sessionId) => useDefaultSession || sessionId !== void 0 ? stub.getProcess(id$1, sessionId) : stub.getProcess(id$1, DISABLE_SESSION_TOKEN),
+		execStream: (command, streamOptions) => {
+			if (useDefaultSession || streamOptions?.sessionId !== void 0) return stub.execStream(command, streamOptions);
+			return stub.execStreamWithSessionToken(command, DISABLE_SESSION_TOKEN, streamOptions);
+		},
+		writeFile: (path$1, content, fileOptions = {}) => useDefaultSession || fileOptions.sessionId !== void 0 ? stub.writeFile(path$1, content, fileOptions) : stub.writeFile(path$1, content, {
+			...fileOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		readFile: (path$1, fileOptions = {}) => {
+			const options$1 = useDefaultSession || fileOptions.sessionId !== void 0 ? fileOptions : {
+				...fileOptions,
+				sessionId: DISABLE_SESSION_TOKEN
+			};
+			if (options$1.encoding === "none") return stub.readFile(path$1, options$1);
+			return stub.readFile(path$1, options$1);
+		},
+		readFileStream: (path$1, fileOptions = {}) => useDefaultSession || fileOptions.sessionId !== void 0 ? stub.readFileStream(path$1, fileOptions) : stub.readFileStream(path$1, { sessionId: DISABLE_SESSION_TOKEN }),
+		mkdir: (path$1, mkdirOptions = {}) => useDefaultSession || mkdirOptions.sessionId !== void 0 ? stub.mkdir(path$1, mkdirOptions) : stub.mkdir(path$1, {
+			...mkdirOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		deleteFile: (path$1) => useDefaultSession ? stub.deleteFile(path$1) : stub.deleteFile(path$1, DISABLE_SESSION_TOKEN),
+		renameFile: (oldPath, newPath) => useDefaultSession ? stub.renameFile(oldPath, newPath) : stub.renameFile(oldPath, newPath, DISABLE_SESSION_TOKEN),
+		moveFile: (sourcePath, destinationPath) => useDefaultSession ? stub.moveFile(sourcePath, destinationPath) : stub.moveFile(sourcePath, destinationPath, DISABLE_SESSION_TOKEN),
+		listFiles: (path$1, listOptions) => useDefaultSession || listOptions?.sessionId !== void 0 ? stub.listFiles(path$1, listOptions) : stub.listFiles(path$1, {
+			...listOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		exists: (path$1, sessionId) => useDefaultSession || sessionId !== void 0 ? stub.exists(path$1, sessionId) : stub.exists(path$1, DISABLE_SESSION_TOKEN),
+		gitCheckout: (repoUrl, gitOptions) => useDefaultSession || gitOptions?.sessionId !== void 0 ? stub.gitCheckout(repoUrl, gitOptions) : stub.gitCheckout(repoUrl, {
+			...gitOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
 		createSession: async (opts) => {
 			return enhanceSession(stub, await stub.createSession(opts));
 		},
 		getSession: async (sessionId) => {
 			return enhanceSession(stub, await stub.getSession(sessionId));
 		},
+		watch: (path$1, options$1 = {}) => useDefaultSession || options$1.sessionId !== void 0 ? stub.watch(path$1, options$1) : stub.watch(path$1, {
+			...options$1,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		checkChanges: (path$1, options$1 = {}) => useDefaultSession || options$1.sessionId !== void 0 ? stub.checkChanges(path$1, options$1) : stub.checkChanges(path$1, {
+			...options$1,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
 		terminal: (request, opts) => proxyTerminal(stub, defaultSessionId, request, opts),
 		wsConnect: connect(stub),
 		desktop: new Proxy({}, { get(_, method) {
@@ -5032,6 +5976,7 @@ var Sandbox = class Sandbox extends Container {
 	sandboxName = null;
 	tunnelsHandler = null;
 	tunnelExitHandler = null;
+	destroyAllTunnels = null;
 	controlCallback;
 	normalizeId = false;
 	defaultSession = null;
@@ -5041,6 +5986,7 @@ var Sandbox = class Sandbox extends Container {
 	logger;
 	keepAliveEnabled = false;
 	activeMounts = /* @__PURE__ */ new Map();
+	currentRuntime;
 	transport = "http";
 	/**
 	* True once transport has been written to storage at least once (either
@@ -5066,8 +6012,23 @@ var Sandbox = class Sandbox extends Container {
 	r2SecretAccessKey = null;
 	r2AccountId = null;
 	backupBucketName = null;
+	backupBucketEndpoint = null;
 	r2Client = null;
 	/**
+	* Lazily-resolved Cloudflare account id for named-tunnel provisioning.
+	* Resolved on first access via `tunnels/credentials.ts` and cached for
+	* the lifetime of this DO instance. See the credentials helper for
+	* the precedence chain.
+	*/
+	tunnelAccountIdPromise = null;
+	/**
+	* Lazily-resolved Cloudflare zone id for named-tunnel provisioning.
+	* Falls back to the single zone the token can see under the resolved
+	* account id when `CLOUDFLARE_ZONE_ID` is not set. Cached for the
+	* lifetime of this DO instance.
+	*/
+	tunnelZoneIdPromise = null;
+	/**
 	* Default container startup timeouts (conservative for production)
 	* Based on Cloudflare docs: "Containers take several minutes to provision"
 	*/
@@ -5226,16 +6187,64 @@ var Sandbox = class Sandbox extends Container {
 			component: "sandbox-do",
 			sandboxId: this.ctx.id.toString()
 		});
+		this.currentRuntime = new CurrentRuntimeIdentity(this.ctx.storage, () => this.getState(), () => this.ctx.container?.running === true);
 		const transportEnv = envObj?.SANDBOX_TRANSPORT;
 		if (transportEnv === "websocket" || transportEnv === "rpc") this.transport = transportEnv;
 		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http", "websocket", or "rpc". Defaulting to "http".`);
 		this.logger.info(`Using ${this.transport} transport`);
 		const backupBucket = envObj?.BACKUP_BUCKET;
 		if (isR2Bucket(backupBucket)) this.backupBucket = backupBucket;
-		this.r2AccountId = getEnvString(envObj, "CLOUDFLARE_ACCOUNT_ID") ?? null;
+		this.r2AccountId = getEnvString(envObj, "CLOUDFLARE_R2_ACCOUNT_ID") ?? getEnvString(envObj, "CLOUDFLARE_ACCOUNT_ID") ?? null;
 		this.r2AccessKeyId = getEnvString(envObj, "R2_ACCESS_KEY_ID") ?? null;
 		this.r2SecretAccessKey = getEnvString(envObj, "R2_SECRET_ACCESS_KEY") ?? null;
 		this.backupBucketName = getEnvString(envObj, "BACKUP_BUCKET_NAME") ?? null;
+		const rawEndpoint = getEnvString(envObj, "BACKUP_BUCKET_ENDPOINT") ?? null;
+		if (rawEndpoint !== null) {
+			let parsed;
+			try {
+				parsed = new URL(rawEndpoint);
+			} catch {
+				const msg = `BACKUP_BUCKET_ENDPOINT is not a valid URL: "${rawEndpoint}". Expected format: https://<account_id>.eu.r2.cloudflarestorage.com`;
+				throw new InvalidBackupConfigError({
+					message: msg,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: msg },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			if (parsed.protocol !== "https:") {
+				const msg = `BACKUP_BUCKET_ENDPOINT must use https://, got "${parsed.protocol.slice(0, -1)}://"`;
+				throw new InvalidBackupConfigError({
+					message: msg,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: msg },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			if (parsed.pathname !== "/") {
+				const msg = `BACKUP_BUCKET_ENDPOINT must not include a path (got "${parsed.pathname}"). Provide only the origin, e.g. https://<account_id>.eu.r2.cloudflarestorage.com`;
+				throw new InvalidBackupConfigError({
+					message: msg,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: msg },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			if (parsed.search !== "" || parsed.hash !== "") {
+				const msg = "BACKUP_BUCKET_ENDPOINT must not include query parameters or fragments. Provide only the origin, e.g. https://<account_id>.eu.r2.cloudflarestorage.com";
+				throw new InvalidBackupConfigError({
+					message: msg,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: msg },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			this.backupBucketEndpoint = parsed.origin;
+		} else this.backupBucketEndpoint = null;
 		if (this.r2AccessKeyId && this.r2SecretAccessKey) this.r2Client = new AwsClient({
 			accessKeyId: this.r2AccessKeyId,
 			secretAccessKey: this.r2SecretAccessKey
@@ -5270,6 +6279,7 @@ var Sandbox = class Sandbox extends Container {
 				this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 				this.tunnelsHandler = null;
 				this.tunnelExitHandler = null;
+				this.destroyAllTunnels = null;
 				previousClient.disconnect();
 			}
 			if (storedTransport) this.hasStoredTransport = true;
@@ -5325,13 +6335,6 @@ var Sandbox = class Sandbox extends Container {
 			}
 		}
 	}
-	/**
-	* RPC method to configure container startup timeouts. Idempotent once
-	* the values have been persisted: re-applying the same timeout set is a
-	* no-op. The transport retry budget is recomputed only when at least
-	* one timeout actually changes. Storage is written before the in-memory
-	* mirror and derived state are updated.
-	*/
 	async setContainerTimeouts(timeouts) {
 		const validated = { ...this.containerTimeouts };
 		if (timeouts.instanceGetTimeoutMS !== void 0) validated.instanceGetTimeoutMS = this.validateTimeout(timeouts.instanceGetTimeoutMS, "instanceGetTimeoutMS", 5e3, 3e5);
@@ -5344,11 +6347,6 @@ var Sandbox = class Sandbox extends Container {
 		this.client.setRetryTimeoutMs(this.computeRetryTimeoutMs());
 		this.logger.debug("Container timeouts updated", this.containerTimeouts);
 	}
-	/**
-	* RPC method to set the transport protocol. Idempotent once the value
-	* has been persisted: re-applying the same transport is a no-op.
-	* Storage is written before the in-memory state and client are updated.
-	*/
 	async setTransport(transport) {
 		if (transport !== "http" && transport !== "websocket" && transport !== "rpc") {
 			this.logger.warn(`Invalid transport value: "${transport}". Must be "http", "websocket", or "rpc". Ignoring.`);
@@ -5363,23 +6361,16 @@ var Sandbox = class Sandbox extends Container {
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		this.tunnelsHandler = null;
 		this.tunnelExitHandler = null;
+		this.destroyAllTunnels = null;
 		previousClient.disconnect();
 		this.renewActivityTimeout();
 		this.logger.debug("Transport updated", { transport });
 	}
-	/**
-	* 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$1) {
 		const parseAndValidate = (envVar, name, min, max) => {
 			const defaultValue = this.DEFAULT_CONTAINER_TIMEOUTS[name];
@@ -5742,7 +6733,7 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async createPasswordFile(passwordFilePath, bucket, credentials) {
 		const content = `${bucket}:${credentials.accessKeyId}:${credentials.secretAccessKey}`;
-		await this.writeFile(passwordFilePath, content);
+		await this.client.files.writeFile(passwordFilePath, content, DISABLE_SESSION_TOKEN);
 		await this.execInternal(`chmod 0600 ${shellEscape(passwordFilePath)}`);
 	}
 	/**
@@ -5842,6 +6833,9 @@ var Sandbox = class Sandbox extends Container {
 		let outcome = "error";
 		let caughtError;
 		try {
+			await this.ctx.storage.delete(PORT_TOKENS_STORAGE_KEY);
+			await this.clearActivePreviewPorts();
+			await this.currentRuntime.clear();
 			if (this.ctx.container?.running) try {
 				await this.client.desktop.stop();
 			} catch {}
@@ -5866,8 +6860,14 @@ var Sandbox = class Sandbox extends Container {
 					await this.deletePasswordFile(mountInfo.passwordFilePath);
 				}
 			}
-			await this.ctx.storage.delete("portTokens");
+			try {
+				this.ensureTunnelsBuilt();
+				await this.destroyAllTunnels?.();
+			} catch (error) {
+				this.logger.warn("Failed to tear down tunnels during destroy()", { error: error instanceof Error ? error.message : String(error) });
+			}
 			await this.ctx.storage.delete("tunnels");
+			await this.ctx.storage.delete("tunnels:meta");
 			this.client.disconnect();
 			outcome = "success";
 			await super.destroy();
@@ -5887,75 +6887,20 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async onStart() {
 		this.logger.debug("Sandbox started");
+		await this.currentRuntime.markStarted();
 		this.checkVersionCompatibility().catch((error) => {
 			this.logger.error("Version compatibility check failed", error instanceof Error ? error : new Error(String(error)));
 		});
 		try {
-			await this.restoreExposedPorts();
-		} catch (error) {
-			this.logger.error("Failed to restore exposed ports after container start", error instanceof Error ? error : new Error(String(error)));
-		}
-		try {
-			await this.ctx.storage.delete("tunnels");
+			await pruneTunnelsForRestart(this.ctx.storage);
 		} catch (error) {
-			this.logger.error("Failed to clear tunnel storage after container start", error instanceof Error ? error : new Error(String(error)));
+			this.logger.error("Failed to reconcile tunnel storage after container start", error instanceof Error ? error : new Error(String(error)));
 		}
 	}
-	/**
-	* Re-expose ports on the container runtime using tokens persisted in DO
-	* storage. Called from onStart() after a container (re)start.
-	*
-	* The DO storage holds the source of truth for which ports should be
-	* exposed, which tokens authorize them, and the friendly name (if any)
-	* that the caller set when first exposing the port. If a port is already
-	* exposed on the container this is a no-op for that port. Individual port
-	* failures are logged but do not abort the overall restore — a transient
-	* failure for one port must not prevent the others from being restored.
-	*/
-	async restoreExposedPorts() {
-		const savedTokens = await this.readPortTokens();
-		const portEntries = Object.entries(savedTokens);
-		if (portEntries.length === 0) return;
-		const startTime = Date.now();
-		let restored = 0;
-		let skipped = 0;
-		let failed = 0;
-		const sessionId = await this.ensureDefaultSession();
-		const exposedSet = await this.client.ports.getExposedPorts(sessionId).then((response) => new Set(response.ports.map((p) => p.port))).catch((error) => {
-			this.logger.warn("Failed to fetch exposed ports for restore; assuming none exposed", { error: error instanceof Error ? error.message : String(error) });
-			return /* @__PURE__ */ new Set();
-		});
-		for (const [portStr, entry] of portEntries) {
-			const port = Number.parseInt(portStr, 10);
-			if (!Number.isFinite(port) || !validatePort(port)) {
-				this.logger.warn("Skipping restore of invalid port in storage", { port: portStr });
-				failed++;
-				continue;
-			}
-			if (exposedSet.has(port)) {
-				skipped++;
-				continue;
-			}
-			try {
-				await this.client.ports.exposePort(port, sessionId, entry.name);
-				restored++;
-			} catch (error) {
-				failed++;
-				this.logger.warn("Failed to re-expose port on container restart", {
-					port,
-					error: error instanceof Error ? error.message : String(error)
-				});
-			}
-		}
-		logCanonicalEvent(this.logger, {
-			event: "port.restore",
-			outcome: failed === 0 ? "success" : "error",
-			durationMs: Date.now() - startTime,
-			restored,
-			skipped,
-			failed,
-			total: portEntries.length
-		});
+	async stop(signal) {
+		await this.currentRuntime.clear();
+		await this.clearActivePreviewPorts();
+		await super.stop(signal);
 	}
 	/**
 	* Read the `portTokens` map from DO storage, normalizing the legacy
@@ -5963,12 +6908,32 @@ var Sandbox = class Sandbox extends Container {
 	* ({ token, name? }). The legacy format predates port-name persistence and
 	* can appear on any DO whose storage was written before that change.
 	*/
-	async readPortTokens() {
-		const raw = await this.ctx.storage.get("portTokens") ?? {};
+	async readPortTokens(storage = this.ctx.storage) {
+		const raw = await storage.get(PORT_TOKENS_STORAGE_KEY) ?? {};
 		const normalized = {};
 		for (const [port, value] of Object.entries(raw)) normalized[port] = typeof value === "string" ? { token: value } : value;
 		return normalized;
 	}
+	async readActivePreviewPorts(storage = this.ctx.storage) {
+		return await storage.get(ACTIVE_PREVIEW_PORTS_STORAGE_KEY) ?? {};
+	}
+	async writeActivePreviewPorts(activations, storage = this.ctx.storage) {
+		if (Object.keys(activations).length === 0) {
+			await storage.delete(ACTIVE_PREVIEW_PORTS_STORAGE_KEY);
+			return;
+		}
+		await storage.put(ACTIVE_PREVIEW_PORTS_STORAGE_KEY, activations);
+	}
+	async readPreviewState(storage = this.ctx.storage) {
+		const [tokens, activations] = await Promise.all([this.readPortTokens(storage), this.readActivePreviewPorts(storage)]);
+		return {
+			tokens,
+			activations
+		};
+	}
+	async clearActivePreviewPorts() {
+		await this.ctx.storage.delete(ACTIVE_PREVIEW_PORTS_STORAGE_KEY);
+	}
 	/**
 	* Check if the container version matches the SDK version
 	* Logs a warning if there's a mismatch
@@ -6001,6 +6966,13 @@ var Sandbox = class Sandbox extends Container {
 		this.containerGeneration++;
 		this.defaultSession = null;
 		this.defaultSessionInit = null;
+		await this.currentRuntime.clear();
+		await this.clearActivePreviewPorts();
+		try {
+			await pruneTunnelsForRestart(this.ctx.storage);
+		} catch (error) {
+			this.logger.error("Failed to reconcile tunnel storage after container stop", error instanceof Error ? error : new Error(String(error)));
+		}
 		this.client.disconnect();
 		let hadR2EgressMount = false;
 		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
@@ -6222,6 +7194,99 @@ var Sandbox = class Sandbox extends Container {
 			await super.onActivityExpired();
 		}
 	}
+	isPreviewProxyRequest(request) {
+		return request.headers.get(PREVIEW_PROXY_HEADER) === "1";
+	}
+	invalidPreviewTokenResponse() {
+		return new Response(JSON.stringify({
+			error: "Access denied: Invalid token or port not exposed",
+			code: "INVALID_TOKEN"
+		}), {
+			status: 404,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	stalePreviewURLResponse() {
+		return new Response(JSON.stringify({
+			error: "Preview URL is stale because the sandbox runtime is not active",
+			code: "STALE_PREVIEW_URL"
+		}), {
+			status: 410,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	getPreviewForwardingContainer() {
+		return this.ctx.container;
+	}
+	beginPreviewForward() {
+		const lifecycle = this;
+		lifecycle.inflightRequests = (lifecycle.inflightRequests ?? 0) + 1;
+		this.renewActivityTimeout();
+		let settled = false;
+		return () => {
+			if (settled) return;
+			settled = true;
+			lifecycle.inflightRequests = Math.max(0, (lifecycle.inflightRequests ?? 0) - 1);
+			if (lifecycle.inflightRequests === 0) this.renewActivityTimeout();
+		};
+	}
+	async fetchPreviewIfRunning(request, port, runtime) {
+		const container = this.getPreviewForwardingContainer();
+		const state = await this.getState();
+		if (!container?.running || state.status !== "healthy") return this.stalePreviewURLResponse();
+		if (!await this.currentRuntime.isActive(runtime)) return this.stalePreviewURLResponse();
+		const result = await forwardPreviewRequest(container.getTcpPort(port), request, {
+			beginForward: () => this.beginPreviewForward(),
+			renewActivity: () => this.renewActivityTimeout()
+		});
+		if (result.status === "network-lost") {
+			if (!await this.currentRuntime.isActive(runtime)) return this.stalePreviewURLResponse();
+			return new Response("Container suddenly disconnected, try again", { status: 500 });
+		}
+		return result.response;
+	}
+	buildPreviewProxyRequest(request, port, sandboxId) {
+		const url = new URL(request.url);
+		const proxyUrl = `http://localhost:${port}${url.pathname}${url.search}`;
+		const headers = new Headers(request.headers);
+		for (const header of PREVIEW_PROXY_HEADERS) headers.delete(header);
+		headers.set("X-Original-URL", request.url);
+		headers.set("X-Forwarded-Host", url.hostname);
+		headers.set("X-Forwarded-Proto", url.protocol.replace(":", ""));
+		headers.set("X-Sandbox-Name", this.sandboxName ?? sandboxId);
+		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") return new Request(request, {
+			headers,
+			redirect: "manual"
+		});
+		return new Request(proxyUrl, {
+			method: request.method,
+			headers,
+			body: request.body,
+			duplex: "half",
+			redirect: "manual"
+		});
+	}
+	async proxyPreviewRequest(request) {
+		const portValue = request.headers.get(PREVIEW_PROXY_PORT_HEADER);
+		const token = request.headers.get(PREVIEW_PROXY_TOKEN_HEADER);
+		const sandboxId = request.headers.get(PREVIEW_PROXY_SANDBOX_ID_HEADER);
+		const port = portValue === null ? NaN : Number.parseInt(portValue, 10);
+		if (!Number.isFinite(port) || !validatePort(port) || !token || !sandboxId) return this.invalidPreviewTokenResponse();
+		const proxyRequest = this.buildPreviewProxyRequest(request, port, sandboxId);
+		const validation = await this.validatePreviewURLForRuntime(port, token);
+		if (validation.status === "invalid") return this.invalidPreviewTokenResponse();
+		if (validation.status === "stale") {
+			this.logger.warn("Stale preview URL blocked", {
+				port,
+				sandboxId,
+				containerStatus: validation.containerStatus,
+				reason: validation.reason,
+				method: request.method
+			});
+			return this.stalePreviewURLResponse();
+		}
+		return await this.fetchPreviewIfRunning(proxyRequest, port, validation.runtime);
+	}
 	async fetch(request) {
 		const traceId = TraceContext.fromHeaders(request.headers) || TraceContext.generate();
 		const requestLogger = this.logger.child({
@@ -6229,6 +7294,7 @@ var Sandbox = class Sandbox extends Container {
 			operation: "fetch"
 		});
 		const url = new URL(request.url);
+		if (this.isPreviewProxyRequest(request)) return await this.proxyPreviewRequest(request);
 		if (!this.sandboxName && request.headers.has("X-Sandbox-Name")) {
 			const name = request.headers.get("X-Sandbox-Name");
 			this.sandboxName = name;
@@ -6320,10 +7386,78 @@ var Sandbox = class Sandbox extends Container {
 		if (containerPlacementId === void 0) return;
 		await this.ctx.storage.put("containerPlacementId", containerPlacementId);
 	}
+	async resolveExecution(explicitSessionId) {
+		if (explicitSessionId !== void 0) {
+			this.validateExplicitSessionId(explicitSessionId);
+			if (explicitSessionId === DISABLE_SESSION_TOKEN) return { kind: "sessionless" };
+			return {
+				kind: "session",
+				sessionId: explicitSessionId
+			};
+		}
+		return {
+			kind: "session",
+			sessionId: await this.ensureDefaultSession()
+		};
+	}
+	validateExplicitSessionId(sessionId) {
+		if (sessionId.trim().length === 0) throw new Error("sessionId must not be empty or whitespace");
+	}
+	serializeExecutionContext(context) {
+		if (context.kind === "sessionless") return DISABLE_SESSION_TOKEN;
+		return context.sessionId;
+	}
+	getPublicExecutionSessionId(sessionId) {
+		return sessionId === DISABLE_SESSION_TOKEN ? void 0 : sessionId;
+	}
+	/**
+	* Resolves the session ID to annotate returned Process objects.
+	*
+	* Unlike `resolveExecution`, this is synchronous and never creates a
+	* session. When the default session hasn't been established yet, it returns
+	* `undefined` rather than triggering session creation. The resolved value is
+	* only used to populate `Process.sessionId` on the returned object — it is
+	* never sent to the container API.
+	*/
+	getProcessSessionBinding(explicitSessionId) {
+		if (explicitSessionId !== void 0) {
+			this.validateExplicitSessionId(explicitSessionId);
+			if (explicitSessionId === DISABLE_SESSION_TOKEN) return;
+			return explicitSessionId;
+		}
+		return this.defaultSession ?? void 0;
+	}
+	resolveExecutionEnv(sessionId, env$1) {
+		if (sessionId === DISABLE_SESSION_TOKEN) {
+			const mergedEnv = filterEnvVars({
+				...this.envVars,
+				...env$1 ?? {}
+			});
+			return Object.keys(mergedEnv).length > 0 ? mergedEnv : void 0;
+		}
+		if (env$1 === void 0) return;
+		const filteredEnv = filterEnvVars(env$1);
+		return Object.keys(filteredEnv).length > 0 ? filteredEnv : void 0;
+	}
+	buildExecutionRequestOptions(sessionId, options) {
+		const env$1 = this.resolveExecutionEnv(sessionId, options?.env);
+		if (options?.timeout === void 0 && env$1 === void 0 && options?.cwd === void 0 && options?.origin === void 0) return;
+		return {
+			...options?.timeout !== void 0 && { timeoutMs: options.timeout },
+			...env$1 !== void 0 && { env: env$1 },
+			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...options?.origin !== void 0 && { origin: options.origin }
+		};
+	}
 	async exec(command, options) {
-		const session = await this.ensureDefaultSession();
+		const context = await this.resolveExecution();
+		const session = this.serializeExecutionContext(context);
 		return this.execWithSession(command, session, options);
 	}
+	async execWithSessionToken(command, sessionId, options) {
+		this.validateExplicitSessionId(sessionId);
+		return this.execWithSession(command, sessionId, options);
+	}
 	/**
 	* Execute an infrastructure command (backup, mount, env setup, etc.)
 	* tagged with origin: 'internal' so logging demotes it to debug level.
@@ -6346,15 +7480,11 @@ var Sandbox = class Sandbox extends Container {
 			let result;
 			if (options?.stream && options?.onOutput) result = await this.executeWithStreaming(command, sessionId, options, startTime, timestamp);
 			else {
-				const commandOptions = options && (options.timeout !== void 0 || options.env !== void 0 || options.cwd !== void 0 || options.origin !== void 0) ? {
-					timeoutMs: options.timeout,
-					env: options.env,
-					cwd: options.cwd,
-					origin: options.origin
-				} : void 0;
+				const commandOptions = this.buildExecutionRequestOptions(sessionId, options);
 				const response = await this.client.commands.execute(command, sessionId, commandOptions);
 				const duration = Date.now() - startTime;
-				result = this.mapExecuteResponseToExecResult(response, duration, sessionId);
+				const publicSessionId = this.getPublicExecutionSessionId(sessionId);
+				result = this.mapExecuteResponseToExecResult(response, duration, publicSessionId);
 			}
 			execOutcome = {
 				exitCode: result.exitCode,
@@ -6373,7 +7503,7 @@ var Sandbox = class Sandbox extends Container {
 				command,
 				exitCode: execOutcome?.exitCode,
 				durationMs: Date.now() - startTime,
-				sessionId,
+				sessionId: this.getPublicExecutionSessionId(sessionId),
 				origin: options?.origin ?? "user",
 				error: execError ?? void 0,
 				errorMessage: execError?.message
@@ -6384,12 +7514,8 @@ var Sandbox = class Sandbox extends Container {
 		let stdout = "";
 		let stderr = "";
 		try {
-			const stream = await this.client.commands.executeStream(command, sessionId, {
-				timeoutMs: options.timeout,
-				env: options.env,
-				cwd: options.cwd,
-				origin: options.origin
-			});
+			const commandOptions = this.buildExecutionRequestOptions(sessionId, options);
+			const stream = await this.client.commands.executeStream(command, sessionId, commandOptions);
 			for await (const event of parseSSEStream(stream)) {
 				if (options.signal?.aborted) throw new Error("Operation was aborted");
 				switch (event.type) {
@@ -6411,7 +7537,7 @@ var Sandbox = class Sandbox extends Container {
 							command,
 							duration,
 							timestamp,
-							sessionId
+							sessionId: this.getPublicExecutionSessionId(sessionId)
 						};
 					}
 					case "error": throw new Error(event.data || "Command execution failed");
@@ -6687,12 +7813,16 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async startProcess(command, options, sessionId) {
 		try {
-			const session = sessionId ?? await this.ensureDefaultSession();
+			const execution = await this.resolveExecution(sessionId);
+			const session = this.serializeExecutionContext(execution);
+			const processSession = this.getProcessSessionBinding(session);
 			const requestOptions = {
+				...this.buildExecutionRequestOptions(session, {
+					timeout: options?.timeout,
+					env: options?.env,
+					cwd: options?.cwd
+				}),
 				...options?.processId !== void 0 && { processId: options.processId },
-				...options?.timeout !== void 0 && { timeoutMs: options.timeout },
-				...options?.env !== void 0 && { env: filterEnvVars(options.env) },
-				...options?.cwd !== void 0 && { cwd: options.cwd },
 				...options?.encoding !== void 0 && { encoding: options.encoding },
 				...options?.autoCleanup !== void 0 && { autoCleanup: options.autoCleanup }
 			};
@@ -6705,7 +7835,7 @@ var Sandbox = class Sandbox extends Container {
 				startTime: /* @__PURE__ */ new Date(),
 				endTime: void 0,
 				exitCode: void 0
-			}, session);
+			}, processSession);
 			if (options?.onStart) options.onStart(processObj);
 			if (options?.onOutput || options?.onExit) this.startProcessCallbackStream(response.processId, options).catch(() => {});
 			return processObj;
@@ -6733,13 +7863,14 @@ var Sandbox = class Sandbox extends Container {
 					if (options.onExit) options.onExit(event.exitCode ?? null);
 					return;
 			}
+			throw new Error("Stream ended without completion event");
 		} catch (error) {
 			if (options.onError && error instanceof Error) options.onError(error);
 			this.logger.error("Background process streaming failed", error instanceof Error ? error : new Error(String(error)), { processId });
 		}
 	}
 	async listProcesses(sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const session = this.getProcessSessionBinding(sessionId);
 		return (await this.client.processes.listProcesses()).processes.map((processData) => this.createProcessFromDTO({
 			id: processData.id,
 			pid: processData.pid,
@@ -6751,22 +7882,24 @@ var Sandbox = class Sandbox extends Container {
 		}, session));
 	}
 	async getProcess(id, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
-		const response = await this.client.processes.getProcess(id).catch((e) => {
-			if (e instanceof ProcessNotFoundError) return null;
-			throw e;
-		});
-		if (!response?.process) return null;
-		const processData = response.process;
-		return this.createProcessFromDTO({
-			id: processData.id,
-			pid: processData.pid,
-			command: processData.command,
-			status: processData.status,
-			startTime: processData.startTime,
-			endTime: processData.endTime,
-			exitCode: processData.exitCode
-		}, session);
+		const session = this.getProcessSessionBinding(sessionId);
+		try {
+			const response = await this.client.processes.getProcess(id);
+			if (!response.process) return null;
+			const processData = response.process;
+			return this.createProcessFromDTO({
+				id: processData.id,
+				pid: processData.pid,
+				command: processData.command,
+				status: processData.status,
+				startTime: processData.startTime,
+				endTime: processData.endTime,
+				exitCode: processData.exitCode
+			}, session);
+		} catch (error) {
+			if (error instanceof ProcessNotFoundError) return null;
+			throw error;
+		}
 	}
 	async killProcess(id, signal, sessionId) {
 		await this.client.processes.killProcess(id);
@@ -6787,23 +7920,29 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async execStream(command, options) {
 		if (options?.signal?.aborted) throw new Error("Operation was aborted");
-		const session = await this.ensureDefaultSession();
-		return this.client.commands.executeStream(command, session, {
-			timeoutMs: options?.timeout,
+		const context = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(context);
+		const executionOptions = this.buildExecutionRequestOptions(session, {
+			timeout: options?.timeout,
 			env: options?.env,
 			cwd: options?.cwd
 		});
+		return this.client.commands.executeStream(command, session, executionOptions);
+	}
+	async execStreamWithSessionToken(command, sessionId, options) {
+		this.validateExplicitSessionId(sessionId);
+		return this.execStreamWithSession(command, sessionId, options);
 	}
 	/**
 	* Internal session-aware execStream implementation
 	*/
 	async execStreamWithSession(command, sessionId, options) {
 		if (options?.signal?.aborted) throw new Error("Operation was aborted");
-		return this.client.commands.executeStream(command, sessionId, {
-			timeoutMs: options?.timeout,
+		return this.client.commands.executeStream(command, sessionId, this.buildExecutionRequestOptions(sessionId, {
+			timeout: options?.timeout,
 			env: options?.env,
 			cwd: options?.cwd
-		});
+		}));
 	}
 	/**
 	* Stream logs from a background process as a ReadableStream.
@@ -6813,7 +7952,8 @@ var Sandbox = class Sandbox extends Container {
 		return this.client.processes.streamProcessLogs(processId);
 	}
 	async gitCheckout(repoUrl, options) {
-		const session = options?.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.git.checkout(repoUrl, session, {
 			branch: options?.branch,
 			targetDir: options?.targetDir,
@@ -6822,28 +7962,34 @@ var Sandbox = class Sandbox extends Container {
 		});
 	}
 	async mkdir(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.mkdir(path$1, session, { recursive: options.recursive });
 	}
 	async writeFile(path$1, content, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		if (content instanceof ReadableStream) return this.client.files.writeFileStream(path$1, content, session);
 		return this.client.files.writeFile(path$1, content, session, { encoding: options.encoding });
 	}
 	async deleteFile(path$1, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.deleteFile(path$1, session);
 	}
 	async renameFile(oldPath, newPath, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.renameFile(oldPath, newPath, session);
 	}
 	async moveFile(sourcePath, destinationPath, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.moveFile(sourcePath, destinationPath, session);
 	}
 	async readFile(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		if (options.encoding === "none") return this.client.files.readFile(path$1, session, { encoding: "none" });
 		return this.client.files.readFile(path$1, session, { encoding: options.encoding });
 	}
@@ -6854,15 +8000,18 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Optional session ID
 	*/
 	async readFileStream(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.readFileStream(path$1, session);
 	}
 	async listFiles(path$1, options) {
-		const session = await this.ensureDefaultSession();
+		const context = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(context);
 		return this.client.files.listFiles(path$1, session, options);
 	}
 	async exists(path$1, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.exists(path$1, session);
 	}
 	/**
@@ -6879,17 +8028,10 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async getDesktopStreamUrl(hostname, options) {
 		if ((await this.client.desktop.status()).status === "inactive") throw new Error("Desktop is not running. Call sandbox.desktop.start() first.");
-		let url;
-		try {
-			url = (await this.exposePort(6080, {
-				hostname,
-				token: options?.token
-			})).url;
-		} catch {
-			const existingEntry = (await this.readPortTokens())["6080"];
-			if (existingEntry && this.sandboxName) url = this.constructPreviewUrl(6080, this.sandboxName, hostname, existingEntry.token);
-			else throw new Error("Failed to get desktop stream URL: port 6080 could not be exposed and no existing token found.");
-		}
+		const url = (await this.exposePort(6080, {
+			hostname,
+			token: options?.token
+		})).url;
 		try {
 			await this.waitForPort({
 				portToCheck: 6080,
@@ -6913,7 +8055,8 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Watch options
 	*/
 	async watch(path$1, options = {}) {
-		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const sessionId = this.serializeExecutionContext(execution);
 		return this.client.watch.watch({
 			path: path$1,
 			recursive: options.recursive,
@@ -6933,7 +8076,8 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Change-check options
 	*/
 	async checkChanges(path$1, options = {}) {
-		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const sessionId = this.serializeExecutionContext(execution);
 		return this.client.watch.checkChanges({
 			path: path$1,
 			recursive: options.recursive,
@@ -6946,11 +8090,10 @@ var Sandbox = class Sandbox extends Container {
 	/**
 	* Expose a port and get a preview URL for accessing services running in the sandbox
 	*
-	* Preview URLs survive transient container restarts: the token and any
-	* friendly name are persisted in Durable Object storage, and the port is
-	* automatically re-exposed on the container when it comes back up. Tokens
-	* are cleared only on explicit `unexposePort()` or full sandbox
-	* `destroy()`.
+	* Preview URL authorization survives transient container restarts, but
+	* forwarding is active only for the runtime where `exposePort()` was last
+	* called. Call `exposePort()` again after a restart to reactivate an
+	* existing URL for the current runtime.
 	*
 	* @param port - Port number to expose (1024-65535)
 	* @param options - Configuration options
@@ -6987,27 +8130,33 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
-			let token;
-			if (options.token !== void 0) {
-				this.validateCustomToken(options.token);
-				token = options.token;
-			} else token = this.generatePortToken();
-			const tokens = await this.readPortTokens();
-			const existingPort = Object.entries(tokens).find(([p, entry]) => entry.token === token && p !== port.toString());
-			if (existingPort) throw new SandboxSecurityError(`Token '${token}' is already in use by port ${existingPort[0]}. Please use a different token.`);
-			const sessionId = await this.ensureDefaultSession();
-			await this.client.ports.exposePort(port, sessionId, options?.name);
-			tokens[port.toString()] = {
-				token,
-				name: options?.name
-			};
-			await this.ctx.storage.put("portTokens", tokens);
+			if (options.token !== void 0) this.validateCustomToken(options.token);
+			await this.ensureDefaultSession();
+			let runtime = await this.currentRuntime.get();
+			runtime = runtime ?? await this.currentRuntime.markStarted();
+			await this.currentRuntime.assertActive(runtime);
+			const token = await this.ctx.storage.transaction(async (txn) => {
+				const tokens = await this.readPortTokens(txn);
+				const existingEntry = tokens[port.toString()];
+				const nextToken = options.token ?? existingEntry?.token ?? this.generatePortToken();
+				const existingPort = Object.entries(tokens).find(([p, entry]) => entry.token === nextToken && p !== port.toString());
+				if (existingPort) throw new SandboxSecurityError(`Token '${nextToken}' is already in use by port ${existingPort[0]}. Please use a different token.`);
+				const activations = await this.readActivePreviewPorts(txn);
+				tokens[port.toString()] = {
+					token: nextToken,
+					name: options.name
+				};
+				activations[port.toString()] = runtime.scope({ token: nextToken });
+				await Promise.all([txn.put(PORT_TOKENS_STORAGE_KEY, tokens), this.writeActivePreviewPorts(activations, txn)]);
+				return nextToken;
+			});
+			await this.currentRuntime.assertActive(runtime);
 			const url = this.constructPreviewUrl(port, this.sandboxName, options.hostname, token);
 			outcome = "success";
 			return {
 				url,
 				port,
-				name: options?.name
+				name: options.name
 			};
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
@@ -7018,29 +8167,37 @@ var Sandbox = class Sandbox extends Container {
 				outcome,
 				port,
 				durationMs: Date.now() - exposeStartTime,
-				name: options?.name,
+				name: options.name,
 				hostname: options.hostname,
 				error: caughtError
 			});
 		}
 	}
+	/**
+	* Revoke preview URL authorization and current-runtime activation for a port.
+	*
+	* Revocation is idempotent: calling this for a port with no preview state is
+	* still successful. The operation clears Durable Object-owned preview state
+	* only and does not contact, probe, wake, or clean up the container runtime.
+	*/
 	async unexposePort(port) {
 		const unexposeStartTime = Date.now();
 		let outcome = "error";
 		let caughtError;
 		try {
 			if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
-			const tokens = await this.readPortTokens();
-			if (tokens[port.toString()]) {
-				delete tokens[port.toString()];
-				await this.ctx.storage.put("portTokens", tokens);
-			}
-			const sessionId = await this.ensureDefaultSession();
-			try {
-				await this.client.ports.unexposePort(port, sessionId);
-			} catch (error) {
-				if (!(error instanceof PortNotExposedError)) throw error;
-			}
+			await this.ctx.storage.transaction(async (txn) => {
+				const tokens = await this.readPortTokens(txn);
+				if (tokens[port.toString()]) {
+					delete tokens[port.toString()];
+					await txn.put(PORT_TOKENS_STORAGE_KEY, tokens);
+				}
+				const activations = await this.readActivePreviewPorts(txn);
+				if (activations[port.toString()]) {
+					delete activations[port.toString()];
+					await this.writeActivePreviewPorts(activations, txn);
+				}
+			});
 			outcome = "success";
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
@@ -7055,23 +8212,17 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
+	/**
+	* Returns preview URLs that are currently forwardable in the active runtime.
+	* Durable authorization without current-runtime activation is omitted.
+	*/
 	async getExposedPorts(hostname) {
-		const sessionId = await this.ensureDefaultSession();
-		const response = await this.client.ports.getExposedPorts(sessionId);
 		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
-		const tokens = await this.readPortTokens();
-		return response.ports.flatMap((port) => {
-			const entry = tokens[port.port.toString()];
-			if (!entry) {
-				this.logger.warn("Port exposed on container but no token in storage; omitting from preview URL list", { port: port.port });
-				return [];
-			}
-			return [{
-				url: this.constructPreviewUrl(port.port, this.sandboxName, hostname, entry.token),
-				port: port.port,
-				status: port.status
-			}];
-		});
+		return (await this.getCurrentPreviewPorts()).map(({ port, entry }) => ({
+			url: this.constructPreviewUrl(port, this.sandboxName, hostname, entry.token),
+			port,
+			status: "active"
+		}));
 	}
 	/**
 	* Namespaced tunnel API. Quick tunnels are zero-config preview URLs
@@ -7107,26 +8258,172 @@ var Sandbox = class Sandbox extends Container {
 		const built = createTunnelsHandler({
 			client: this.client,
 			storage: this.ctx.storage,
-			logger: this.logger
+			logger: this.logger,
+			sandboxId: this.ctx.id.toString(),
+			getNamedTunnelConfig: async () => {
+				const envObj = this.env;
+				const token = getEnvString(envObj, "CLOUDFLARE_API_TOKEN");
+				if (!token) throw new Error("Named tunnels require CLOUDFLARE_API_TOKEN. Set it as a secret in your wrangler.jsonc.");
+				const accountId = await this.getTunnelAccountId();
+				return {
+					token,
+					accountId,
+					zoneId: await this.getTunnelZoneId(token, accountId)
+				};
+			}
 		});
 		this.tunnelsHandler = built.tunnels;
 		this.tunnelExitHandler = built.handleTunnelExit;
+		this.destroyAllTunnels = built.destroyAll;
 	}
-	async isPortExposed(port) {
-		try {
-			const sessionId = await this.ensureDefaultSession();
-			return (await this.client.ports.getExposedPorts(sessionId)).ports.some((exposedPort) => exposedPort.port === port);
-		} catch (error) {
-			this.logger.error("Error checking if port is exposed", error instanceof Error ? error : new Error(String(error)), { port });
-			return false;
+	/**
+	* Resolve the Cloudflare account id used for named-tunnel provisioning.
+	*
+	* Memoised for the lifetime of this DO instance. The first call may hit
+	* `GET /user/tokens/verify` to derive the account id from the configured
+	* `CLOUDFLARE_API_TOKEN`; subsequent calls return the cached promise.
+	*
+	* Only successful resolutions are cached: a rejected lookup clears the
+	* slot so the next caller retries. Otherwise a transient failure on
+	* first use would permanently poison every later named-tunnel `get()`
+	* on this DO instance.
+	*/
+	getTunnelAccountId() {
+		if (!this.tunnelAccountIdPromise) {
+			const pending = resolveAccountId(this.env, { overrideKey: "CLOUDFLARE_TUNNEL_ACCOUNT_ID" });
+			this.tunnelAccountIdPromise = pending;
+			pending.catch(() => {
+				if (this.tunnelAccountIdPromise === pending) this.tunnelAccountIdPromise = null;
+			});
 		}
+		return this.tunnelAccountIdPromise;
 	}
+	/**
+	* Resolve the Cloudflare zone id used for named-tunnel provisioning.
+	*
+	* Memoised for the lifetime of this DO instance. Falls back to the
+	* single zone the token can see under `accountId` via `GET /zones`
+	* when `CLOUDFLARE_ZONE_ID` is not set. Failed lookups clear the cache
+	* so the next caller retries — see `getTunnelAccountId` for the
+	* rationale.
+	*/
+	getTunnelZoneId(token, accountId) {
+		if (!this.tunnelZoneIdPromise) {
+			const pending = resolveZoneId(this.env, {
+				token,
+				accountId
+			});
+			this.tunnelZoneIdPromise = pending;
+			pending.catch(() => {
+				if (this.tunnelZoneIdPromise === pending) this.tunnelZoneIdPromise = null;
+			});
+		}
+		return this.tunnelZoneIdPromise;
+	}
+	/**
+	* Returns whether a port is currently preview-forwardable.
+	* This checks Durable Object-owned auth and runtime activation without
+	* contacting or waking the container.
+	*/
+	async isPortExposed(port) {
+		if (!validatePort(port)) return false;
+		return (await this.getCurrentPreviewPorts()).some((activePort) => activePort.port === port);
+	}
+	/**
+	* Checks durable preview URL authorization for a port/token pair.
+	*
+	* This does not check whether the port is activated for the current runtime
+	* and is not sufficient to decide whether preview traffic may forward.
+	*/
 	async validatePortToken(port, token) {
 		const entry = (await this.readPortTokens())[port.toString()];
 		if (!entry) return false;
+		return this.previewTokensMatch(entry.token, token);
+	}
+	async validatePreviewURLForRuntime(port, token) {
+		const containerState = await this.getState();
+		const containerRunning = this.ctx.container?.running === true;
+		const { tokens, activations, runtime } = await this.ctx.storage.transaction(async (txn) => {
+			const [previewState, runtime$1] = await Promise.all([this.readPreviewState(txn), this.currentRuntime.getStored(txn)]);
+			return {
+				...previewState,
+				runtime: runtime$1
+			};
+		});
+		const entry = tokens[port.toString()];
+		if (!entry) return { status: "invalid" };
+		if (!this.previewTokensMatch(entry.token, token)) return { status: "invalid" };
+		if (containerState.status !== "healthy") return {
+			status: "stale",
+			reason: "runtime-not-healthy",
+			containerStatus: containerState.status
+		};
+		if (!containerRunning) return {
+			status: "stale",
+			reason: "runtime-not-running",
+			containerStatus: containerState.status
+		};
+		if (!runtime) return {
+			status: "stale",
+			reason: "missing-runtime-id",
+			containerStatus: containerState.status
+		};
+		const activation = activations[port.toString()];
+		if (!activation) return {
+			status: "stale",
+			reason: "missing-activation",
+			containerStatus: containerState.status
+		};
+		if (!runtime.owns(activation)) return {
+			status: "stale",
+			reason: "runtime-mismatch",
+			containerStatus: containerState.status
+		};
+		if (!this.previewTokensMatch(activation.token, token)) {
+			this.logger.warn("Preview URL activation token mismatch", {
+				port,
+				runtimeIdentityID: runtime.id
+			});
+			return {
+				status: "stale",
+				reason: "token-mismatch",
+				containerStatus: containerState.status
+			};
+		}
+		return {
+			status: "active",
+			runtime
+		};
+	}
+	async getCurrentPreviewPorts() {
+		const containerState = await this.getState();
+		const containerRunning = this.ctx.container?.running === true;
+		const { tokens, activations, runtime } = await this.ctx.storage.transaction(async (txn) => {
+			const [previewState, runtime$1] = await Promise.all([this.readPreviewState(txn), this.currentRuntime.getStored(txn)]);
+			return {
+				...previewState,
+				runtime: runtime$1
+			};
+		});
+		if (containerState.status !== "healthy" || !containerRunning || !runtime) return [];
+		const activePorts = [];
+		for (const [portKey, activation] of Object.entries(activations)) {
+			const port = Number.parseInt(portKey, 10);
+			const entry = tokens[portKey];
+			if (!entry || !Number.isInteger(port) || !validatePort(port)) continue;
+			if (!runtime.owns(activation)) continue;
+			if (!this.previewTokensMatch(entry.token, activation.token)) continue;
+			activePorts.push({
+				port,
+				entry
+			});
+		}
+		return activePorts.sort((a, b) => a.port - b.port);
+	}
+	previewTokensMatch(expected, actual) {
 		const encoder = new TextEncoder();
-		const a = encoder.encode(entry.token);
-		const b = encoder.encode(token);
+		const a = encoder.encode(expected);
+		const b = encoder.encode(actual);
 		try {
 			return crypto.subtle.timingSafeEqual(a, b);
 		} catch {
@@ -7174,6 +8471,7 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async createSession(options) {
 		const sessionId = options?.id || `session-${Date.now()}`;
+		if (sessionId === DISABLE_SESSION_TOKEN) throw new Error(`Session ID '${DISABLE_SESSION_TOKEN}' is reserved for internal use`);
 		const filteredEnv = filterEnvVars({
 			...this.envVars,
 			...options?.env ?? {}
@@ -7457,10 +8755,10 @@ var Sandbox = class Sandbox extends Container {
 	* Returns validated presigned URL configuration or throws if not configured.
 	* All credential fields plus the R2 binding are required for backup to work.
 	*/
-	requirePresignedUrlSupport() {
+	requirePresignedURLSupport() {
 		if (!this.r2Client || !this.r2AccountId || !this.backupBucketName) {
 			const missing = [];
-			if (!this.r2AccountId) missing.push("CLOUDFLARE_ACCOUNT_ID");
+			if (!this.r2AccountId) missing.push("CLOUDFLARE_R2_ACCOUNT_ID or CLOUDFLARE_ACCOUNT_ID");
 			if (!this.r2AccessKeyId) missing.push("R2_ACCESS_KEY_ID");
 			if (!this.r2SecretAccessKey) missing.push("R2_SECRET_ACCESS_KEY");
 			if (!this.backupBucketName) missing.push("BACKUP_BUCKET_NAME");
@@ -7478,15 +8776,21 @@ var Sandbox = class Sandbox extends Container {
 			bucketName: this.backupBucketName
 		};
 	}
+	getBackupBucketEndpoint(accountId) {
+		return this.backupBucketEndpoint ?? `https://${accountId}.r2.cloudflarestorage.com`;
+	}
+	getBackupObjectURL(accountId, bucketName, r2Key) {
+		const encodedBucket = encodeURIComponent(bucketName);
+		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
+		return new URL(`${this.getBackupBucketEndpoint(accountId)}/${encodedBucket}/${encodedKey}`);
+	}
 	/**
 	* Generate a presigned GET URL for downloading an object from R2.
 	* The container can curl this URL directly without credentials.
 	*/
-	async generatePresignedGetUrl(r2Key) {
-		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
-		const encodedBucket = encodeURIComponent(bucketName);
-		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
-		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
+	async generatePresignedGetURL(r2Key) {
+		const { client, accountId, bucketName } = this.requirePresignedURLSupport();
+		const url = this.getBackupObjectURL(accountId, bucketName, r2Key);
 		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
 		return (await client.sign(new Request(url), { aws: { signQuery: true } })).url;
 	}
@@ -7494,11 +8798,9 @@ var Sandbox = class Sandbox extends Container {
 	* Generate a presigned PUT URL for uploading an object to R2.
 	* The container can curl PUT to this URL directly without credentials.
 	*/
-	async generatePresignedPutUrl(r2Key) {
-		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
-		const encodedBucket = encodeURIComponent(bucketName);
-		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
-		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
+	async generatePresignedPutURL(r2Key) {
+		const { client, accountId, bucketName } = this.requirePresignedURLSupport();
+		const url = this.getBackupObjectURL(accountId, bucketName, r2Key);
 		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
 		return (await client.sign(new Request(url, { method: "PUT" }), { aws: { signQuery: true } })).url;
 	}
@@ -7508,7 +8810,7 @@ var Sandbox = class Sandbox extends Container {
 	* ~24 MB/s throughput vs ~0.6 MB/s for base64 readFile.
 	*/
 	async uploadBackupPresigned(archivePath, r2Key, archiveSize, backupId, dir, backupSession) {
-		const presignedUrl = await this.generatePresignedPutUrl(r2Key);
+		const presignedURL = await this.generatePresignedPutURL(r2Key);
 		const curlCmd = [
 			"curl -sSf",
 			"-X PUT",
@@ -7518,7 +8820,7 @@ var Sandbox = class Sandbox extends Container {
 			"--retry 2",
 			"--retry-max-time 60",
 			`-T ${shellEscape(archivePath)}`,
-			shellEscape(presignedUrl)
+			shellEscape(presignedURL)
 		].join(" ");
 		const result = await this.execWithSession(curlCmd, backupSession, {
 			timeout: 181e4,
@@ -7552,11 +8854,9 @@ var Sandbox = class Sandbox extends Container {
 	/**
 	* Generate a presigned PUT URL for a single part in a multipart upload.
 	*/
-	async generatePresignedPartUrl(r2Key, uploadId, partNumber) {
-		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
-		const encodedBucket = encodeURIComponent(bucketName);
-		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
-		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
+	async generatePresignedPartURL(r2Key, uploadId, partNumber) {
+		const { client, accountId, bucketName } = this.requirePresignedURLSupport();
+		const url = this.getBackupObjectURL(accountId, bucketName, r2Key);
 		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
 		url.searchParams.set("partNumber", String(partNumber));
 		url.searchParams.set("uploadId", uploadId);
@@ -7571,9 +8871,9 @@ var Sandbox = class Sandbox extends Container {
 		const targetParts = calculatePartCount(sizeBytes, BACKUP_MULTIPART_TARGET_PARTS, BACKUP_MULTIPART_MAX_PARTS);
 		const numParts = Math.min(targetParts, Math.floor(sizeBytes / BACKUP_MULTIPART_MIN_PART_SIZE));
 		if (numParts <= 1) return this.uploadBackupPresigned(archivePath, r2Key, sizeBytes, backupId, dir, backupSession);
-		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
-		const objectUrl = `https://${accountId}.r2.cloudflarestorage.com/${encodeURIComponent(bucketName)}/${r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/")}`;
-		const createResp = await client.fetch(`${objectUrl}?uploads`, { method: "POST" });
+		const { client, accountId, bucketName } = this.requirePresignedURLSupport();
+		const objectURL = this.getBackupObjectURL(accountId, bucketName, r2Key).toString();
+		const createResp = await client.fetch(`${objectURL}?uploads`, { method: "POST" });
 		if (!createResp.ok) throw new BackupCreateError({
 			message: `Failed to initiate multipart upload: HTTP ${createResp.status}`,
 			code: ErrorCode.BACKUP_CREATE_FAILED,
@@ -7596,7 +8896,7 @@ var Sandbox = class Sandbox extends Container {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
 		const abortMultipart = async () => {
-			await client.fetch(`${objectUrl}?uploadId=${encodeURIComponent(uploadId)}`, { method: "DELETE" }).catch(() => {});
+			await client.fetch(`${objectURL}?uploadId=${encodeURIComponent(uploadId)}`, { method: "DELETE" }).catch(() => {});
 		};
 		try {
 			const partSize = Math.ceil(sizeBytes / numParts);
@@ -7607,7 +8907,7 @@ var Sandbox = class Sandbox extends Container {
 				size: i === numParts - 1 ? sizeBytes - i * partSize : partSize
 			})).map(async (part) => ({
 				...part,
-				url: await this.generatePresignedPartUrl(r2Key, uploadId, part.partNumber)
+				url: await this.generatePresignedPartURL(r2Key, uploadId, part.partNumber)
 			})));
 			let uploadResult;
 			try {
@@ -7638,7 +8938,7 @@ var Sandbox = class Sandbox extends Container {
 				...uploadResult.parts.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${p.etag}</ETag></Part>`),
 				"</CompleteMultipartUpload>"
 			].join("");
-			const completeResp = await client.fetch(`${objectUrl}?uploadId=${encodeURIComponent(uploadId)}`, {
+			const completeResp = await client.fetch(`${objectURL}?uploadId=${encodeURIComponent(uploadId)}`, {
 				method: "POST",
 				headers: { "Content-Type": "application/xml" },
 				body: completeXml
@@ -7680,7 +8980,7 @@ var Sandbox = class Sandbox extends Container {
 	* with dd using byte offsets, then atomically moved to the final path.
 	*/
 	async downloadBackupParallel(archivePath, r2Key, expectedSize, backupId, dir, backupSession) {
-		const presignedUrl = await this.generatePresignedGetUrl(r2Key);
+		const presignedURL = await this.generatePresignedGetURL(r2Key);
 		await this.execWithSession(`mkdir -p ${BACKUP_CONTAINER_DIR}`, backupSession, { origin: "internal" });
 		const tmpPath = `${archivePath}.tmp`;
 		if (expectedSize < BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE) {
@@ -7691,7 +8991,7 @@ var Sandbox = class Sandbox extends Container {
 				"--retry 2",
 				"--retry-max-time 60",
 				`-o ${shellEscape(tmpPath)}`,
-				shellEscape(presignedUrl)
+				shellEscape(presignedURL)
 			].join(" ");
 			const result = await this.execWithSession(curlCmd, backupSession, {
 				timeout: 181e4,
@@ -7724,7 +9024,7 @@ var Sandbox = class Sandbox extends Container {
 				"--connect-timeout 10",
 				"--max-time 1800",
 				`-H ${shellEscape(`Range: bytes=${range}`)}`,
-				shellEscape(presignedUrl),
+				shellEscape(presignedURL),
 				"|",
 				"dd",
 				`of=${shellEscape(tmpPath)}`,
@@ -7830,7 +9130,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async doCreateBackup(options) {
 		const bucket = this.requireBackupBucket();
-		this.requirePresignedUrlSupport();
+		this.requirePresignedURLSupport();
 		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [], compression, multipart = true } = options;
 		const backupStartTime = Date.now();
 		let backupId;
@@ -8130,7 +9430,7 @@ var Sandbox = class Sandbox extends Container {
 	async doRestoreBackup(backup) {
 		const restoreStartTime = Date.now();
 		const bucket = this.requireBackupBucket();
-		this.requirePresignedUrlSupport();
+		this.requirePresignedURLSupport();
 		const { id, dir } = backup;
 		let outcome = "error";
 		let caughtError;
@@ -8400,5 +9700,5 @@ var Sandbox = class Sandbox extends Container {
 };
 
 //#endregion
-export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, RPCTransportError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y, SessionTerminatedError as z };
-//# sourceMappingURL=sandbox-BcEq4aUF.js.map
+export { DesktopClient as A, DesktopProcessCrashedError as B, streamFile as C, PortClient as D, ProcessClient as E, BackupNotFoundError as F, ProcessReadyTimeoutError as G, DesktopUnavailableError as H, BackupRestoreError as I, RPCTransportError as K, DesktopInvalidCoordinatesError as L, BackupClient as M, BackupCreateError as N, GitClient as O, BackupExpiredError as P, DesktopInvalidOptionsError as R, collectFile as S, UtilityClient as T, InvalidBackupConfigError as U, DesktopStartFailedError as V, ProcessExitedBeforeReadyError as W, CodeInterpreter as _, PREVIEW_PROXY_HEADERS as a, validatePort as b, PREVIEW_PROXY_TOKEN_HEADER as c, InvalidMountConfigError as d, MissingCredentialsError as f, responseToAsyncIterable as g, parseSSEStream as h, PREVIEW_PROXY_HEADER as i, CommandClient as j, FileClient as k, BucketMountError as l, asyncIterableToSSEStream as m, getSandbox as n, PREVIEW_PROXY_PORT_HEADER as o, S3FSMountError as p, SessionTerminatedError as q, proxyTerminal as r, PREVIEW_PROXY_SANDBOX_ID_HEADER as s, Sandbox as t, BucketUnmountError as u, SandboxSecurityError as v, SandboxClient as w, validateTunnelName as x, sanitizeSandboxId as y, DesktopNotStartedError as z };
+//# sourceMappingURL=sandbox-DQxTkLyY.js.map