@cloudflare/sandbox 0.13.0-next.649.1 → 0.13.0-next.681.1

package/Dockerfile

@@ -1,5 +1,5 @@
 # Bun version — override via --build-arg BUN_VERSION=$(cat .bun-version)
-ARG BUN_VERSION=1
+ARG BUN_VERSION=1.3.14
 # Node version — override via --build-arg NODE_VERSION=24
 ARG NODE_VERSION=24
 # cloudflared release — shared across glibc and musl image variants.
@@ -186,12 +186,9 @@ COPY --from=bun-binary /usr/local/bin/bun /usr/local/bin/bun
 # Copy standalone binary
 COPY --from=builder /app/packages/sandbox-container/dist/sandbox /container-server/sandbox
 
-# Set up container server directory for executors
+# Set up container server directory
 WORKDIR /container-server
 
-# Copy bundled JavaScript executor (runs on Node or Bun for code interpreter)
-COPY --from=builder /app/packages/sandbox-container/dist/runtime/executors/javascript/node_executor.js ./dist/runtime/executors/javascript/
-
 # Copy legacy JS bundle for backwards compatibility
 # 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/
@@ -245,14 +242,13 @@ RUN ln -s /usr/local/python/bin/python3.11 /usr/local/bin/python3.11 && \
 # Set Python 3.11 as default python3
 RUN update-alternatives --install /usr/bin/python3 python3 /usr/local/bin/python3.11 1
 
-# Install Python packages for data science and code interpreter
+# Install Python packages for data science and the code interpreter extension.
+# The interpreter runtime itself is provisioned by the @cloudflare/sandbox/interpreter
+# extension; this image only provides the Python toolchain it relies on.
 RUN --mount=type=cache,target=/root/.cache/pip \
     pip3 install --no-cache-dir matplotlib numpy pandas ipython
 
-# Copy Python executor
-COPY --from=builder /app/packages/sandbox-container/src/runtime/executors/python/ipython_executor.py ./dist/runtime/executors/python/
-
-# Enable all interpreter pools
+# Pre-warm pool sizes consumed by the interpreter extension sidecar
 ENV PYTHON_POOL_MIN_SIZE=3
 ENV JAVASCRIPT_POOL_MIN_SIZE=3
 ENV TYPESCRIPT_POOL_MIN_SIZE=3
@@ -318,7 +314,6 @@ COPY --from=builder /app/packages/sandbox-container/dist/sandbox-musl /container
 
 WORKDIR /container-server
 
-COPY --from=builder /app/packages/sandbox-container/dist/runtime/executors/javascript/node_executor.js ./dist/runtime/executors/javascript/
 COPY --from=builder /app/packages/sandbox-container/dist/index.js ./dist/
 
 RUN mkdir -p /workspace

package/README.md

@@ -82,7 +82,7 @@ export default {
 
     // Execute Python code
     if (url.pathname === '/run') {
-      const result = await sandbox.exec('python3 -c "print(2 + 2)"');
+      const result = await sandbox.exec('python3 -c "print(2 + 2)"').output();
       return Response.json({ output: result.stdout, success: result.success });
     }
 
@@ -154,7 +154,7 @@ Notes:
 - **Edge-Native** - Runs on Cloudflare's global network
 - **Code Interpreter** - Execute Python and JavaScript with rich outputs
 - **File System Access** - Read, write, and manage files
-- **Command Execution** - Run any command with streaming support
+- **Command Execution** - Run commands with a Containers-style process handle, streaming output, stdin, and background process control
 - **Preview URLs** - Expose services with public URLs
 - **Quick tunnels** - Zero-config `*.trycloudflare.com` URLs via `sandbox.tunnels.get(port)`
 - **Git Integration** - Clone repositories directly

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":";;;;;;;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"}
+{"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,QAAA,EAAsB,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,8 @@
-import "../dist-mAH_7Ui7.js";
-import "../errors-CpoDEfUZ.js";
-import { S as validateTunnelName, r as getSandbox, w as streamFile, x as validatePort, y as SandboxSecurityError } from "../sandbox-B-FLGbkP.js";
+import "../dist-BStBkGIC.js";
+import "../errors-k3B8orjH.js";
+import "../errors-ewgSNicb.js";
+import { S as streamFile, g as validateTunnelName, h as validatePort, m as SandboxSecurityError, n as getSandbox } from "../sandbox-boKWPIcd.js";
+import "../extensions-CepYdzro.js";
 import { DurableObject, env } from "cloudflare:workers";
 import { Hono } from "hono";
 
@@ -454,7 +456,7 @@ const OPENAPI_SCHEMA = {
 					type: "string",
 					pattern: "^[a-zA-Z0-9._-]{1,128}$"
 				},
-				description: "Scope this operation to a specific session. Uses the default session if omitted."
+				description: "Scope this operation to an explicit session. If omitted, the operation uses top-level sandbox behavior."
 			}],
 			requestBody: {
 				required: true,
@@ -618,7 +620,7 @@ const OPENAPI_SCHEMA = {
 							type: "string",
 							pattern: "^[a-zA-Z0-9._-]{1,128}$"
 						},
-						description: "Scope this operation to a specific session. Uses the default session if omitted."
+						description: "Scope this operation to an explicit session. If omitted, the operation uses top-level sandbox behavior."
 					}
 				],
 				responses: {
@@ -694,7 +696,7 @@ const OPENAPI_SCHEMA = {
 							type: "string",
 							pattern: "^[a-zA-Z0-9._-]{1,128}$"
 						},
-						description: "Scope this operation to a specific session. Uses the default session if omitted."
+						description: "Scope this operation to an explicit session. If omitted, the operation uses top-level sandbox behavior."
 					}
 				],
 				requestBody: {
@@ -737,12 +739,12 @@ const OPENAPI_SCHEMA = {
 		},
 		"/v1/sandbox/{id}/pty": { get: {
 			operationId: "ptyTerminal",
-			summary: "Open a PTY terminal session via WebSocket",
-			description: "Upgrades the HTTP connection to a WebSocket and proxies it to a PTY shell inside the sandbox.\n\n**WebSocket frame protocol:**\n\n| Direction | Frame type | Content |\n|-----------|------------|--------------------------------------------------|\n| Client → Server | Binary | UTF-8 encoded keystrokes / input |\n| Server → Client | Binary | Terminal output (including ANSI escape sequences) |\n| Client → Server | Text (JSON) | Control messages, e.g. `{\"type\":\"resize\",\"cols\":120,\"rows\":30}` |\n| Server → Client | Text (JSON) | Status messages: `ready`, `exit`, `error` |\n\n**Status messages (server → client):**\n- `{\"type\":\"ready\"}` — PTY is accepting input\n- `{\"type\":\"exit\",\"code\":0,\"signal\":\"SIGTERM\"}` — PTY exited\n- `{\"type\":\"error\",\"message\":\"...\"}` — error occurred\n\nIf the client disconnects, the PTY stays alive; reconnecting replays buffered output.",
+			summary: "Open a terminal via WebSocket",
+			description: "Upgrades the HTTP connection to a WebSocket and proxies it to a PTY shell inside the sandbox.\n\n**A terminal ID is required**, supplied via either the `terminalId` query parameter or the `Terminal-Id` header (header takes precedence). The terminal ID is a stable resource name: reconnecting with the same ID reattaches to the same live PTY while the sandbox container is alive. If the sandbox container restarts (for example after it sleeps), connecting with the same ID creates a fresh shell — prior PTY state and process history are not preserved.\n\n**WebSocket frame protocol:**\n\n| Direction | Frame type | Content |\n|-----------|------------|--------------------------------------------------|\n| Client → Server | Binary | UTF-8 encoded keystrokes / input |\n| Server → Client | Binary | Terminal output (including ANSI escape sequences) |\n| Client → Server | Text (JSON) | Control messages, e.g. `{\"type\":\"resize\",\"cols\":120,\"rows\":30}` |\n| Server → Client | Text (JSON) | Status messages: `ready`, `exit`, `error` |\n\n**Status messages (server → client):**\n- `{\"type\":\"ready\"}` — PTY is accepting input\n- `{\"type\":\"exit\",\"code\":0,\"signal\":\"SIGTERM\"}` — PTY exited\n- `{\"type\":\"error\",\"message\":\"...\"}` — error occurred\n\nIf the client disconnects, the terminal stays alive while the sandbox container is alive; reconnect with the same terminal ID to reattach.",
 			"x-codeSamples": [{
 				lang: "JavaScript",
 				label: "WebSocket",
-				source: "const ws = new WebSocket(\"wss://$HOST/v1/sandbox/my-sandbox/pty?cols=120&rows=30\");\nws.binaryType = \"arraybuffer\";\nws.onmessage = (e) => { /* handle binary output or JSON status */ };"
+				source: "const ws = new WebSocket(\"wss://$HOST/v1/sandbox/my-sandbox/pty?terminalId=term-1&cols=120&rows=30\");\nws.binaryType = \"arraybuffer\";\nws.onmessage = (e) => { /* handle binary output or JSON status */ };"
 			}],
 			parameters: [
 				{
@@ -780,21 +782,31 @@ const OPENAPI_SCHEMA = {
 					description: "Shell binary to run (e.g. `/bin/bash`). Uses the container default if omitted."
 				},
 				{
-					name: "session",
+					name: "cwd",
 					in: "query",
 					required: false,
 					schema: { type: "string" },
-					description: "SDK session ID. If provided, the PTY is scoped to this session."
+					description: "Initial working directory for newly created terminal resources."
 				},
 				{
-					name: "Session-Id",
+					name: "terminalId",
+					in: "query",
+					required: false,
+					schema: {
+						type: "string",
+						pattern: "^[a-zA-Z0-9._-]{1,128}$"
+					},
+					description: "Terminal resource ID. Required unless the `Terminal-Id` request header is supplied. Stable name for this terminal resource: reuse the same ID across reconnects to reattach to the same live PTY. After the sandbox container restarts, the same ID creates a new shell. Ignored when `Terminal-Id` header is also present (header takes precedence)."
+				},
+				{
+					name: "Terminal-Id",
 					in: "header",
 					required: false,
 					schema: {
 						type: "string",
 						pattern: "^[a-zA-Z0-9._-]{1,128}$"
 					},
-					description: "Scope this operation to a specific session. Uses the default session if omitted."
+					description: "Terminal resource ID. Required unless the `terminalId` query parameter is supplied. Takes precedence over the `terminalId` query parameter when both are present. Same stable-ID semantics apply: same ID reattaches to the live PTY; after the sandbox container restarts a new shell is created."
 				}
 			],
 			responses: {
@@ -1045,7 +1057,7 @@ const OPENAPI_SCHEMA = {
 		"/v1/sandbox/{id}/session": { post: {
 			operationId: "createSession",
 			summary: "Create an execution session",
-			description: "Sessions isolate working directory and environment variables across commands. The returned session ID is used with the `Session-Id` header on exec, file, and PTY endpoints.",
+			description: "Sessions isolate working directory and environment variables across commands. The returned session ID is used with the `Session-Id` header on exec and file endpoints.",
 			parameters: [{
 				name: "id",
 				in: "path",
@@ -1102,7 +1114,7 @@ const OPENAPI_SCHEMA = {
 		"/v1/sandbox/{id}/session/{sid}": { delete: {
 			operationId: "deleteSession",
 			summary: "Delete an execution session",
-			description: "Removes a named session. The default session cannot be deleted.",
+			description: "Removes an explicit execution session.",
 			parameters: [{
 				name: "id",
 				in: "path",
@@ -1136,11 +1148,11 @@ const OPENAPI_SCHEMA = {
 				},
 				"401": { $ref: "#/components/responses/Unauthorized" },
 				"502": {
-					description: "Session deletion failed (e.g. cannot delete default session).",
+					description: "Session deletion failed.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "cannot delete the default session",
+							error: "session deletion failed",
 							code: "session_error"
 						}
 					} }
@@ -1942,31 +1954,36 @@ function createBridgeApp(config) {
 			closed = true;
 			lastWrite.then(() => writer.close()).catch(() => {});
 		}
-		executor.exec(command, {
-			...opts,
-			stream: true,
-			onOutput(stream, data) {
-				writeSSE(stream, toBase64(data));
-			},
-			onComplete(result) {
-				writeSSE("exit", JSON.stringify({ exit_code: result.exitCode }));
-				closeStream();
-			},
-			onError(err) {
+		(async () => {
+			try {
+				const proc = await executor.exec(command, opts);
+				const decoder = new TextDecoder();
+				const pump = async (stream, name) => {
+					if (!stream) return;
+					const reader = stream.getReader();
+					try {
+						for (;;) {
+							const { value, done } = await reader.read();
+							if (done) break;
+							if (value && value.byteLength > 0) writeSSE(name, toBase64(decoder.decode(value)));
+						}
+					} finally {
+						reader.releaseLock();
+					}
+				};
+				await Promise.all([pump(proc.stdout, "stdout"), pump(proc.stderr, "stderr")]);
+				const exitCode = await proc.exitCode;
+				writeSSE("exit", JSON.stringify({ exit_code: exitCode }));
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
 				writeSSE("error", JSON.stringify({
-					error: err.message,
-					code: "exec_error"
+					error: `exec failed: ${msg}`,
+					code: "exec_transport_error"
 				}));
+			} finally {
 				closeStream();
 			}
-		}).catch((err) => {
-			const msg = err instanceof Error ? err.message : String(err);
-			writeSSE("error", JSON.stringify({
-				error: `exec failed: ${msg}`,
-				code: "exec_transport_error"
-			}));
-			closeStream();
-		});
+		})();
 		return new Response(readable, {
 			status: 200,
 			headers: {
@@ -2072,22 +2089,24 @@ function createBridgeApp(config) {
 		const colsParam = c.req.query("cols");
 		const rowsParam = c.req.query("rows");
 		const shell = c.req.query("shell");
-		const sessionId = c.req.header("Session-Id") || c.req.query("session");
+		const cwd = c.req.query("cwd");
+		const terminalId = c.req.header("Terminal-Id") ?? c.req.query("terminalId") ?? c.req.query("terminal");
 		const cols = colsParam ? Number(colsParam) : 80;
 		const rows = rowsParam ? Number(rowsParam) : 24;
 		if (Number.isNaN(cols) || Number.isNaN(rows)) return errorJson("cols and rows must be valid numbers", "invalid_request", 400);
-		const opts = {
+		const terminalOptions = {};
+		const connectOptions = {
 			cols,
 			rows
 		};
-		if (shell) opts.shell = shell;
+		if (shell) terminalOptions.shell = shell;
+		if (cwd) terminalOptions.cwd = cwd;
+		if (!terminalId) return errorJson("terminalId query parameter or Terminal-Id header required", "invalid_request", 400);
+		const validatedId = validateSessionId(terminalId);
+		if (!validatedId) return errorJson("Invalid terminal ID format", "invalid_request", 400);
+		terminalOptions.id = validatedId;
 		try {
-			if (sessionId) {
-				const validatedId = validateSessionId(sessionId);
-				if (!validatedId) return errorJson("Invalid session ID format", "invalid_request", 400);
-				return await (await sandbox.getSession(validatedId)).terminal(c.req.raw, opts);
-			}
-			return await sandbox.terminal(c.req.raw, opts);
+			return await sandbox.terminal(terminalOptions).connect(c.req.raw, connectOptions);
 		} catch (err) {
 			return errorJson(`terminal failed: ${err instanceof Error ? err.message : String(err)}`, "exec_transport_error", 502);
 		}
@@ -2102,7 +2121,7 @@ function createBridgeApp(config) {
 		const excludeArgs = excludes.map((rel) => `--exclude ${shellQuote(`./${rel.replace(/^\.\//, "")}`)}`).join(" ");
 		const tarCmd = excludeArgs ? `tar cf ${shellQuote(tmpPath)} ${excludeArgs} -C ${shellQuote(root)} .` : `tar cf ${shellQuote(tmpPath)} -C ${shellQuote(root)} .`;
 		try {
-			const result = await sandbox.exec(tarCmd);
+			const result = await sandbox.exec(tarCmd).output({ encoding: "utf8" });
 			if (result.exitCode !== 0) return errorJson(`tar failed (exit ${result.exitCode}): ${result.stderr}`, "workspace_archive_read_error", 502);
 			const stream = await sandbox.readFileStream(tmpPath);
 			sandbox.exec(`rm -f ${shellQuote(tmpPath)}`).catch(() => {});
@@ -2134,7 +2153,7 @@ function createBridgeApp(config) {
 			const CHUNK = 6144;
 			for (let i = 0; i < tarBytes.length; i += CHUNK) b64 += btoa(String.fromCharCode(...tarBytes.subarray(i, i + CHUNK)));
 			await sandbox.writeFile(tmpPath, b64, { encoding: "base64" });
-			const extractResult = await sandbox.exec(`tar xf ${shellQuote(tmpPath)} -C ${shellQuote(root)} && rm -f ${shellQuote(tmpPath)}`);
+			const extractResult = await sandbox.exec(`tar xf ${shellQuote(tmpPath)} -C ${shellQuote(root)} && rm -f ${shellQuote(tmpPath)}`).output({ encoding: "utf8" });
 			if (extractResult.exitCode !== 0) return errorJson(`tar extract failed (exit ${extractResult.exitCode}): ${extractResult.stderr}`, "workspace_archive_write_error", 502);
 			return c.json({ ok: true });
 		} catch (err) {