@cloudflare/sandbox 0.10.2 → 0.11.0

package/Dockerfile

@@ -2,9 +2,53 @@
 ARG BUN_VERSION=1
 # Node version — override via --build-arg NODE_VERSION=24
 ARG NODE_VERSION=24
+# cloudflared release — shared across glibc and musl image variants.
+# Bump this together with the architecture-specific checksums below.
+ARG CLOUDFLARED_VERSION=2026.3.0
 FROM oven/bun:${BUN_VERSION} AS bun-binary
 FROM node:${NODE_VERSION}-slim AS node-runtime
 
+# ============================================================================
+# cloudflared (Cloudflare Tunnel daemon) — enables sandbox.tunnels.*
+# Version pin lives at the top of this Dockerfile as a global ARG, shared
+# by every image variant so they ship the same release.
+# ============================================================================
+FROM alpine:3.21 AS cloudflared-binary
+
+ARG TARGETARCH
+ARG CLOUDFLARED_VERSION
+ARG CLOUDFLARED_SHA256_AMD64=4a9e50e6d6d798e90fcd01933151a90bf7edd99a0a55c28ad18f2e16263a5c30
+ARG CLOUDFLARED_SHA256_ARM64=0755ba4cbab59980e6148367fcf53a8f3ec85a97deefd63c2420cf7850769bee
+
+# Inject the host's extra CA bundle when downloading behind a TLS-intercepting
+# proxy (e.g. Cloudflare WARP / Zero Trust). 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 \
+        cat /run/secrets/wrangler_ca >> /etc/ssl/certs/ca-certificates.crt; \
+        mkdir -p /usr/local/share/ca-certificates && \
+        cp /run/secrets/wrangler_ca /usr/local/share/ca-certificates/wrangler-dev-ca.crt; \
+    fi && \
+    apk add --no-cache ca-certificates curl && \
+    if [ -f /usr/local/share/ca-certificates/wrangler-dev-ca.crt ]; then \
+        update-ca-certificates; \
+    fi
+
+RUN set -eux; \
+    arch="${TARGETARCH:-}"; \
+    if [ -z "$arch" ]; then \
+      arch="$(apk --print-arch)"; \
+    fi; \
+    case "$arch" in \
+      amd64|x86_64) suffix=amd64; sha="${CLOUDFLARED_SHA256_AMD64}" ;; \
+      arm64|aarch64) 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 /cloudflared "$url"; \
+    echo "$sha  /cloudflared" | sha256sum -c -; \
+    chmod +x /cloudflared; \
+    /cloudflared --version
+
 # Sandbox container images (default and python variants)
 # Multi-stage build optimized for Turborepo monorepo
 
@@ -152,26 +196,8 @@ 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
+COPY --from=cloudflared-binary /cloudflared /usr/local/bin/cloudflared
+RUN cloudflared --version
 
 # Inject the host's extra CA bundle when running locally behind a TLS-
 # intercepting proxy (e.g. Cloudflare WARP / Zero Trust). See
@@ -338,6 +364,11 @@ RUN apk add --no-cache bash file git curl libstdc++ libgcc s3fs-fuse fuse
 
 RUN sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf
 
+# The Alpine variant uses the same cloudflared release asset as the glibc
+# variants. It is a static binary that runs on musl without gcompat.
+COPY --from=cloudflared-binary /cloudflared /usr/local/bin/cloudflared
+RUN cloudflared --version
+
 COPY --from=builder /app/packages/sandbox-container/dist/sandbox-musl /container-server/sandbox
 
 WORKDIR /container-server

package/README.md

@@ -137,8 +137,6 @@ Notes:
   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).

package/dist/bridge/index.js

@@ -1,6 +1,6 @@
 import "../dist-B_eXrP83.js";
-import "../errors-8Hvune8K.js";
-import { h as streamFile, n as getSandbox } from "../sandbox-BcEq4aUF.js";
+import "../errors-COsTRno_.js";
+import { C as streamFile, b as validatePort, n as getSandbox, v as SandboxSecurityError, x as validateTunnelName } from "../sandbox-DQxTkLyY.js";
 import { DurableObject, env } from "cloudflare:workers";
 import { Hono } from "hono";
 
@@ -267,6 +267,50 @@ const OPENAPI_SCHEMA = {
 					example: "/mnt/data"
 				} }
 			},
+			TunnelRequest: {
+				type: "object",
+				properties: { name: {
+					type: "string",
+					description: "Subdomain prefix for a named tunnel, such as `app`. Do not pass a full hostname. Omit to create or reuse an ephemeral tunnel.",
+					example: "app"
+				} }
+			},
+			Tunnel: {
+				type: "object",
+				required: [
+					"id",
+					"port",
+					"url",
+					"hostname",
+					"createdAt"
+				],
+				properties: {
+					id: { type: "string" },
+					port: {
+						type: "integer",
+						description: "Container port served by the tunnel.",
+						example: 8080
+					},
+					url: {
+						type: "string",
+						format: "uri",
+						example: "https://app.example.com"
+					},
+					hostname: {
+						type: "string",
+						example: "app.example.com"
+					},
+					createdAt: {
+						type: "string",
+						format: "date-time"
+					},
+					name: {
+						type: "string",
+						description: "Present for named tunnels only.",
+						example: "app"
+					}
+				}
+			},
 			ErrorResponse: {
 				type: "object",
 				required: ["error", "code"],
@@ -290,7 +334,8 @@ const OPENAPI_SCHEMA = {
 							"pool_error",
 							"mount_error",
 							"unmount_error",
-							"session_error"
+							"session_error",
+							"tunnel_error"
 						]
 					}
 				}
@@ -439,6 +484,103 @@ const OPENAPI_SCHEMA = {
 				}
 			}
 		} },
+		"/v1/sandbox/{id}/tunnel/{port}": {
+			post: {
+				operationId: "createTunnel",
+				summary: "Create or reuse a tunnel for a sandbox port",
+				description: "Returns an existing tunnel for the port when one is already recorded, or provisions one when needed. The service must already be listening inside the sandbox. Omit `name` for an ephemeral `*.trycloudflare.com` tunnel, or pass `name` to choose the subdomain prefix for a named tunnel. Use a value such as `app`, not a full hostname.",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "Ephemeral tunnel",
+					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+				}, {
+					lang: "curl",
+					label: "Named tunnel",
+					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"app\"}'"
+				}],
+				parameters: [{
+					name: "id",
+					in: "path",
+					required: true,
+					schema: { type: "string" },
+					description: "Sandbox instance name."
+				}, {
+					name: "port",
+					in: "path",
+					required: true,
+					schema: {
+						type: "integer",
+						minimum: 1024,
+						maximum: 65535
+					},
+					description: "Container port to tunnel. Port 3000 is reserved."
+				}],
+				requestBody: {
+					required: false,
+					content: { "application/json": { schema: { $ref: "#/components/schemas/TunnelRequest" } } }
+				},
+				responses: {
+					"200": {
+						description: "Tunnel created or reused.",
+						content: { "application/json": { schema: { $ref: "#/components/schemas/Tunnel" } } }
+					},
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"502": {
+						description: "Tunnel creation failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "tunnel failed: cloudflared could not be found",
+								code: "tunnel_error"
+							}
+						} }
+					}
+				}
+			},
+			delete: {
+				operationId: "deleteTunnel",
+				summary: "Delete the tunnel for a sandbox port",
+				description: "Stops the tunnel process for the port and removes any named-tunnel Cloudflare resources tracked by the sandbox.",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "Delete tunnel",
+					source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+				}],
+				parameters: [{
+					name: "id",
+					in: "path",
+					required: true,
+					schema: { type: "string" },
+					description: "Sandbox instance name."
+				}, {
+					name: "port",
+					in: "path",
+					required: true,
+					schema: {
+						type: "integer",
+						minimum: 1024,
+						maximum: 65535
+					},
+					description: "Container port whose tunnel should be deleted. Port 3000 is reserved."
+				}],
+				responses: {
+					"204": { description: "Tunnel deleted or already absent." },
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"502": {
+						description: "Tunnel deletion failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "tunnel failed: cleanup failed",
+								code: "tunnel_error"
+							}
+						} }
+					}
+				}
+			}
+		},
 		"/v1/sandbox/{id}/file/{path}": {
 			get: {
 				operationId: "readFile",
@@ -1632,6 +1774,24 @@ function hasCredentials(options) {
 function isStringArray(value) {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function parseTunnelOptions(rawBody) {
+	if (!rawBody.trim()) return void 0;
+	let body;
+	try {
+		body = JSON.parse(rawBody);
+	} catch {
+		return errorJson("Invalid JSON body", "invalid_request", 400);
+	}
+	if (!body || typeof body !== "object" || Array.isArray(body) || body.name === void 0) return;
+	if (typeof body.name !== "string") return errorJson("name must be a string when provided", "invalid_request", 400);
+	try {
+		validateTunnelName(body.name);
+	} catch (err) {
+		if (err instanceof SandboxSecurityError) return errorJson(err.message, "invalid_request", 400);
+		throw err;
+	}
+	return { name: body.name };
+}
 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);
@@ -1865,6 +2025,30 @@ function createBridgeApp(config) {
 			return errorJson(`write failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
 		}
 	});
+	app.post(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const options = parseTunnelOptions(await c.req.text());
+		if (options instanceof Response) return options;
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			const tunnel = await sandbox.tunnels.get(port, options);
+			return c.json(tunnel);
+		} catch (err) {
+			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
+		}
+	});
+	app.delete(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			await sandbox.tunnels.destroy(port);
+			return c.body(null, 204);
+		} catch (err) {
+			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
+		}
+	});
 	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
 		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
 		try {