@cloudflare/sandbox 0.10.1 → 0.10.2

package/Dockerfile

@@ -152,6 +152,38 @@ COPY --from=builder /app/packages/sandbox-container/dist/runtime/executors/javas
 # Users with custom startup scripts that call `bun /container-server/dist/index.js` need this
 COPY --from=builder /app/packages/sandbox-container/dist/index.js ./dist/
 
+# ============================================================================
+# cloudflared (Cloudflare Tunnel daemon) — enables sandbox.tunnels.*
+# Pinned version with sha256 verification per architecture.
+# Skipped in the musl/Alpine stage (no musl prebuilt).
+# ============================================================================
+ARG CLOUDFLARED_VERSION=2026.3.0
+ARG CLOUDFLARED_SHA256_AMD64=4a9e50e6d6d798e90fcd01933151a90bf7edd99a0a55c28ad18f2e16263a5c30
+ARG CLOUDFLARED_SHA256_ARM64=0755ba4cbab59980e6148367fcf53a8f3ec85a97deefd63c2420cf7850769bee
+RUN set -eux; \
+    arch="$(dpkg --print-architecture)"; \
+    case "$arch" in \
+      amd64) suffix=amd64; sha="${CLOUDFLARED_SHA256_AMD64}" ;; \
+      arm64) suffix=arm64; sha="${CLOUDFLARED_SHA256_ARM64}" ;; \
+      *) echo "Unsupported arch for cloudflared: $arch" >&2; exit 1 ;; \
+    esac; \
+    url="https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-${suffix}"; \
+    curl -fsSL -o /usr/local/bin/cloudflared "$url"; \
+    echo "$sha  /usr/local/bin/cloudflared" | sha256sum -c -; \
+    chmod +x /usr/local/bin/cloudflared; \
+    cloudflared --version
+
+# Inject the host's extra CA bundle when running locally behind a TLS-
+# intercepting proxy (e.g. Cloudflare WARP / Zero Trust). See
+# DOCKER_README.md for the local-dev setup. No-op when the secret
+# isn't passed.
+RUN --mount=type=secret,id=wrangler_ca \
+    if [ -f /run/secrets/wrangler_ca ] && [ -s /run/secrets/wrangler_ca ]; then \
+        cp /run/secrets/wrangler_ca /usr/local/share/ca-certificates/wrangler-dev-ca.crt && \
+        cat /run/secrets/wrangler_ca >> /etc/ssl/certs/ca-certificates.crt && \
+        update-ca-certificates; \
+    fi
+
 RUN mkdir -p /workspace
 
 # Expose the application port (3000 for control)

package/README.md

@@ -98,6 +98,51 @@ export default {
 };
 ```
 
+## Quick tunnels
+
+`sandbox.tunnels.get(port)` exposes a service running inside the
+sandbox on a `*.trycloudflare.com` URL. No Cloudflare account or DNS
+setup required — cloudflared opens a persistent QUIC connection to
+Cloudflare's edge and Cloudflare hands back a hostname.
+
+```ts
+// Inside a Worker with an RPC-transport sandbox:
+const tunnel = await sandbox.tunnels.get(8080);
+console.log(tunnel.url);
+// → https://random-words-here.trycloudflare.com
+
+// Repeated calls for the same port return the same record:
+const same = await sandbox.tunnels.get(8080);
+console.log(same.url === tunnel.url); // true
+
+// Tear down by port number or by the record:
+await sandbox.tunnels.destroy(8080);
+// or: await sandbox.tunnels.destroy(tunnel);
+```
+
+`get()` is idempotent: it consults a per-sandbox cache in Durable
+Object storage, returns the cached record on a hit, and only spawns a
+fresh cloudflared process on a miss. `list()` returns every cached
+tunnel.
+
+Notes:
+
+- Requires the RPC transport. The route-based transport's `tunnels`
+  stub throws "RPC transport required".
+- URLs do **not** survive a container restart. Cloudflare assigns the
+  hostname during cloudflared's startup handshake, so every restart
+  yields a new URL. The SDK clears its cache on container start, so
+  the next `get(port)` after a restart returns a fresh record.
+- The first fetch through a brand-new URL can take a couple of
+  seconds while DNS propagates, even after `get()` resolves.
+- `*.trycloudflare.com` buffers `text/event-stream` responses.
+  WebSockets work fine.
+- The musl/Alpine image variant does not ship cloudflared (no upstream
+  musl prebuilt); `sandbox.tunnels` is unavailable on that variant.
+- Local builds behind a TLS-intercepting proxy (e.g. Cloudflare WARP)
+  need the host CA bundle injected at build time — see
+  [DOCKER_README.md](../../DOCKER_README.md).
+
 ## Documentation
 
 **📖 [Full Documentation](https://developers.cloudflare.com/sandbox/)**
@@ -115,6 +160,7 @@ export default {
 - **File System Access** - Read, write, and manage files
 - **Command Execution** - Run any command with streaming support
 - **Preview URLs** - Expose services with public URLs
+- **Quick tunnels** - Zero-config `*.trycloudflare.com` URLs via `sandbox.tunnels.get(port)`
 - **Git Integration** - Clone repositories directly
 
 ## Contributing

package/dist/bridge/index.d.ts

@@ -2,12 +2,6 @@ import { DurableObject } from "cloudflare:workers";
 
 //#region src/bridge/types.d.ts
 
-/**
- * Wire types and configuration types for the Cloudflare Sandbox Bridge.
- *
- * These types define the JSON payloads exchanged between HTTP clients
- * (e.g. the Python `CloudflareSandboxClient`) and the bridge worker.
- */
 /**
  * Configuration options for the bridge() factory.
  */

package/dist/bridge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bridge/types.ts","../../src/bridge/helpers.ts","../../src/bridge/warm-pool.ts","../../src/bridge/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;AAgCA;;;;;AAKgB,UArCC,YAAA,CAqCD;EAEA;;;;AAehB;;;;ICEgB;IAyBA,QAAA,CAAA,EAAA,MAAA;;;;AC7EhB;AAOA;AAWC;EA6CY,cAAS,CAAA,EAAA,MAAA;EAAsB;;;;;EA6FxB,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFhIH,cAAA;kBAEJ,wBAEJ,mBACJ,WAAW,QAAQ;EGiCR,SAAM,EAAA,UAAA,EH/BN,mBG+BM,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH7Bb,gBG6Ba,CAAA,EAAA,IAAA,GH5BV,OG4BU,CAAA,IAAA,CAAA;EACZ,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHjBO,SAAA;;;;;;;;;;;AAAjB;;;;ACEA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAOA;AAmDU,iBDmBM,oBAAA,CClBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFThB,UElDA,cAAA,CFkDS;;;;ECEV,eAAU,CAAA,EAAA,MAAA;AAyB1B;UCtEiB,SAAA;;;EAPA;EAOA,QAAA,EAAA,MAAS;EAmDhB;EAKG,KAAA,EAAA,MAAS;EAAsB;EA2BH,MAAA,EA3E/B,QA2E+B,CA3EtB,cA2EsB,CAAA;EA6CG;EAYE,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UAzFpC,WAAA,CAKoB;EAAa,OAAA,EAJhC,sBAIgC;;;cAA9B,QAAA,SAAiB,cAAc;ECG5B,QAAA,MAAM;EACZ;EACC,QAAA,cAAA;EACQ;EAAhB,QAAA,WAAA;EAAe;;;;;;;;;;;mCDqBuB;;;;;;sCA6CG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBAUd;WAyBZ;;;;;;;;;;;;;;;;;;;;;;;;AAvMjB;AAWC;AA6CD;;;;;;;;;;AA+IiB,iBC5ID,MAAA,CD4IC,MAAA,EC3IP,cD2IO,EAAA,MAAA,CAAA,EC1IN,YD0IM,CAAA,ECzId,eDyIc,CCzIE,SDyIF,CAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bridge/types.ts","../../src/bridge/helpers.ts","../../src/bridge/warm-pool.ts","../../src/bridge/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6DgB,UAvCC,YAAA,CAuCD;EAEP;;;AAaT;;;;ICJgB,OAAA,CAAA,EAAU,MAAA;IAyBV;;;;AC7EhB;AAOA;AAWC;AA6CD;EAA4C,cAAA,CAAA,EAAA,MAAA;EA2BH;;;;;EAiFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFzIT,cAAA;EGgCD,KAAA,EAAA,OAAM,EH9BT,OG8BS,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH5Bb,gBG4Ba,CAAA,EH3BjB,QG2BiB,GH3BN,OG2BM,CH3BE,QG2BF,CAAA;EACZ,SAAA,EAAA,UAAA,EH1BM,mBG0BN,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EHxBD,gBGwBC,CAAA,EAAA,IAAA,GHvBE,OGuBF,CAAA,IAAA,CAAA;EACC,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHZM,SAAA;;;;;;;;;;;AAAjB;;;;ACJA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAOA;AAmDU,iBDmBM,oBAAA,CClBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFHhB,UExDA,cAAA,CFwDS;;;;ECJV,eAAU,CAAA,EAAA,MAAA;AAyB1B;UCtEiB,SAAA;;;EAPA;EAOA,QAAA,EAAA,MAAS;EAmDhB;EAKG,KAAA,EAAA,MAAS;EAAsB;EA2BH,MAAA,EA3E/B,QA2E+B,CA3EtB,cA2EsB,CAAA;EA6CG;EAYE,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UAzFpC,WAAA,CAKoB;EAAa,OAAA,EAJhC,sBAIgC;;;cAA9B,QAAA,SAAiB,cAAc;ECG5B,QAAA,MAAM;EACZ;EACC,QAAA,cAAA;EACQ;EAAhB,QAAA,WAAA;EAAe;;;;;;;;;;;mCDqBuB;;;;;;sCA6CG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBAUd;WAyBZ;;;;;;;;;;;;;;;;;;;;;;;;AAvMjB;AAWC;AA6CD;;;;;;;;;;AA+IiB,iBC5ID,MAAA,CD4IC,MAAA,EC3IP,cD2IO,EAAA,MAAA,CAAA,EC1IN,YD0IM,CAAA,ECzId,eDyIc,CCzIE,SDyIF,CAAA"}

package/dist/bridge/index.js

@@ -1,6 +1,6 @@
 import "../dist-B_eXrP83.js";
-import "../errors-CBi-O-pF.js";
-import { h as streamFile, n as getSandbox } from "../sandbox-uC1vzWtG.js";
+import "../errors-8Hvune8K.js";
+import { h as streamFile, n as getSandbox } from "../sandbox-BcEq4aUF.js";
 import { DurableObject, env } from "cloudflare:workers";
 import { Hono } from "hono";
 
@@ -208,11 +208,10 @@ const OPENAPI_SCHEMA = {
 			},
 			MountBucketRequestOptions: {
 				type: "object",
-				required: ["endpoint"],
 				properties: {
 					endpoint: {
 						type: "string",
-						description: "S3-compatible endpoint URL.",
+						description: "S3-compatible endpoint URL for remote mounts. Mutually exclusive with top-level `binding`.",
 						example: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com"
 					},
 					readOnly: {
@@ -222,28 +221,35 @@ const OPENAPI_SCHEMA = {
 					},
 					prefix: {
 						type: "string",
-						description: "Optional prefix/subdirectory within the bucket to mount. Must start and end with `/`.",
-						example: "/uploads/images/"
+						description: "Optional prefix/subdirectory within the bucket to mount. Must start with `/`. Trailing slashes are stripped automatically.",
+						example: "/uploads/images"
 					},
 					credentials: {
 						$ref: "#/components/schemas/MountBucketCredentials",
 						description: "Explicit credentials. When omitted, the SDK auto-detects from Worker secrets (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY or AWS equivalents)."
+					},
+					s3fsOptions: {
+						type: "array",
+						items: { type: "string" },
+						description: "Advanced: Override or extend s3fs mount options for both remote mounts and R2 binding mounts.",
+						example: ["nomultipart"]
 					}
 				}
 			},
 			MountBucketRequest: {
 				type: "object",
-				required: [
-					"bucket",
-					"mountPath",
-					"options"
-				],
+				required: ["mountPath", "options"],
 				properties: {
 					bucket: {
 						type: "string",
-						description: "Bucket name.",
+						description: "Remote bucket name for endpoint-based S3-compatible mounts.",
 						example: "my-r2-bucket"
 					},
+					binding: {
+						type: "string",
+						description: "Worker R2 binding name for credential-less R2 binding mounts. Mutually exclusive with `options.endpoint`.",
+						example: "MY_BUCKET"
+					},
 					mountPath: {
 						type: "string",
 						description: "Absolute path in the container to mount at.",
@@ -1614,6 +1620,55 @@ function esc(s) {
 function getSandbox$1(ns, containerUUID) {
 	return getSandbox(ns, containerUUID);
 }
+function hasEndpoint(options) {
+	return "endpoint" in options && typeof options.endpoint === "string";
+}
+function hasEndpointProperty(options) {
+	return "endpoint" in options && options.endpoint !== void 0;
+}
+function hasCredentials(options) {
+	return "credentials" in options && options.credentials !== void 0;
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function validateMountOptions(options, binding) {
+	if ("endpoint" in options && !hasEndpoint(options)) return errorJson("options.endpoint must be a string when provided", "invalid_request", 400);
+	if (binding !== void 0 && typeof binding !== "string") return errorJson("binding must be a string when provided", "invalid_request", 400);
+	if (binding === "") return errorJson("binding must be a non-empty string when provided", "invalid_request", 400);
+	if (binding !== void 0 && hasEndpointProperty(options)) return errorJson("Provide either binding or options.endpoint, not both", "invalid_request", 400);
+	if (options.s3fsOptions !== void 0 && !isStringArray(options.s3fsOptions)) return errorJson("options.s3fsOptions must be an array of strings when provided", "invalid_request", 400);
+	if (options.readOnly !== void 0 && typeof options.readOnly !== "boolean") return errorJson("options.readOnly must be a boolean when provided", "invalid_request", 400);
+	if (options.prefix !== void 0 && typeof options.prefix !== "string") return errorJson("options.prefix must be a string when provided", "invalid_request", 400);
+	if ("credentials" in options && options.credentials !== void 0 && (typeof options.credentials !== "object" || options.credentials === null || typeof options.credentials.accessKeyId !== "string" || typeof options.credentials.secretAccessKey !== "string")) return errorJson("options.credentials must include string accessKeyId and secretAccessKey", "invalid_request", 400);
+	return null;
+}
+function resolveMountBucketName(body) {
+	if (hasEndpoint(body.options)) {
+		if (body.bucket && typeof body.bucket === "string") return body.bucket;
+		return errorJson("bucket must be a non-empty string for remote mounts", "invalid_request", 400);
+	}
+	if (body.binding !== void 0) return body.binding;
+	return errorJson("binding must be a non-empty string for R2 binding mounts", "invalid_request", 400);
+}
+function toSDKMountOptions(options) {
+	if (hasEndpoint(options)) {
+		const remoteOptions = { endpoint: options.endpoint };
+		if (options.readOnly !== void 0) remoteOptions.readOnly = options.readOnly;
+		if (options.prefix !== void 0) remoteOptions.prefix = options.prefix;
+		if (hasCredentials(options)) remoteOptions.credentials = {
+			accessKeyId: options.credentials.accessKeyId,
+			secretAccessKey: options.credentials.secretAccessKey
+		};
+		if (options.s3fsOptions !== void 0) remoteOptions.s3fsOptions = options.s3fsOptions;
+		return remoteOptions;
+	}
+	const r2BindingOptions = {};
+	if (options.readOnly !== void 0) r2BindingOptions.readOnly = options.readOnly;
+	if (options.prefix !== void 0) r2BindingOptions.prefix = options.prefix;
+	if (options.s3fsOptions !== void 0) r2BindingOptions.s3fsOptions = options.s3fsOptions;
+	return r2BindingOptions;
+}
 function createBridgeApp(config) {
 	const app = new Hono();
 	const { sandboxBinding, warmPoolBinding, apiPrefix } = config;
@@ -1902,21 +1957,18 @@ function createBridgeApp(config) {
 		} catch {
 			return errorJson("Invalid JSON body", "invalid_request", 400);
 		}
-		if (!body.bucket || typeof body.bucket !== "string") return errorJson("bucket must be a non-empty string", "invalid_request", 400);
+		if (body.bucket !== void 0 && (typeof body.bucket !== "string" || body.bucket === "")) return errorJson("bucket must be a non-empty string", "invalid_request", 400);
 		if (!body.mountPath || typeof body.mountPath !== "string") return errorJson("mountPath must be a non-empty string", "invalid_request", 400);
 		if (!body.mountPath.startsWith("/")) return errorJson("mountPath must be an absolute path (start with /)", "invalid_request", 400);
-		if (!body.options || typeof body.options !== "object") return errorJson("options must be an object", "invalid_request", 400);
-		if (!body.options.endpoint || typeof body.options.endpoint !== "string") return errorJson("options.endpoint must be a non-empty string", "invalid_request", 400);
+		if (!body.options || typeof body.options !== "object" || Array.isArray(body.options)) return errorJson("options must be an object", "invalid_request", 400);
+		const optionsError = validateMountOptions(body.options, body.binding);
+		if (optionsError) return optionsError;
+		const bucketName = resolveMountBucketName(body);
+		if (bucketName instanceof Response) return bucketName;
 		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		const sdkOptions = { endpoint: body.options.endpoint };
-		if (body.options.readOnly !== void 0) sdkOptions.readOnly = body.options.readOnly;
-		if (body.options.prefix !== void 0) sdkOptions.prefix = body.options.prefix;
-		if (body.options.credentials) sdkOptions.credentials = {
-			accessKeyId: body.options.credentials.accessKeyId,
-			secretAccessKey: body.options.credentials.secretAccessKey
-		};
+		const sdkOptions = toSDKMountOptions(body.options);
 		try {
-			await sandbox.mountBucket(body.bucket, body.mountPath, sdkOptions);
+			await sandbox.mountBucket(bucketName, body.mountPath, sdkOptions);
 			return c.json({ ok: true });
 		} catch (err) {
 			return errorJson(`mount failed: ${err instanceof Error ? err.message : String(err)}`, "mount_error", 502);