@cloudflare/sandbox 0.13.0-next.651.1 → 0.13.0-next.709.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.
@@ -161,7 +161,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     rm -rf /var/cache/apt/* /var/lib/apt/lists/* && \
     apt-get update && apt-get install -y --no-install-recommends \
     s3fs fuse3 squashfs-tools squashfuse fuse-overlayfs \
-    ca-certificates curl wget procps git unzip zip jq file \
+    ca-certificates curl wget procps git unzip zip jq file tini \
     inotify-tools \
     libssl3 zlib1g libbz2-1.0 libreadline8 libsqlite3-0 \
     libncursesw6 libtinfo6 libxml2 libxmlsec1 libffi8 liblzma5 libtk8.6 && \
@@ -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/
@@ -225,7 +222,7 @@ ENV PYTHON_POOL_MIN_SIZE=0
 ENV JAVASCRIPT_POOL_MIN_SIZE=3
 ENV TYPESCRIPT_POOL_MIN_SIZE=3
 
-ENTRYPOINT ["/container-server/sandbox"]
+ENTRYPOINT ["/usr/bin/tini", "--", "/container-server/sandbox"]
 
 # ============================================================================
 # Stage 5b: Python image - full, with Python + data science packages
@@ -245,19 +242,18 @@ 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
 
-ENTRYPOINT ["/container-server/sandbox"]
+ENTRYPOINT ["/usr/bin/tini", "--", "/container-server/sandbox"]
 
 # ============================================================================
 # Stage 5c: OpenCode image - with OpenCode CLI for AI coding agent
@@ -282,7 +278,7 @@ ENV TYPESCRIPT_POOL_MIN_SIZE=3
 # Expose OpenCode server port (in addition to 3000 from runtime-base)
 EXPOSE 4096
 
-ENTRYPOINT ["/container-server/sandbox"]
+ENTRYPOINT ["/usr/bin/tini", "--", "/container-server/sandbox"]
 
 # ============================================================================
 # Stage 5d: Musl image - Alpine-based with musl-linked binary
@@ -305,7 +301,7 @@ RUN --mount=type=secret,id=wrangler_ca \
         apk add --no-cache ca-certificates; \
     fi
 
-RUN apk add --no-cache bash file git curl libstdc++ libgcc s3fs-fuse fuse
+RUN apk add --no-cache bash file git curl libstdc++ libgcc s3fs-fuse fuse tini
 
 RUN sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf
 
@@ -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
@@ -329,4 +324,4 @@ ENV PYTHON_POOL_MIN_SIZE=0
 ENV JAVASCRIPT_POOL_MIN_SIZE=0
 ENV TYPESCRIPT_POOL_MIN_SIZE=0
 
-ENTRYPOINT ["/container-server/sandbox"]
+ENTRYPOINT ["/sbin/tini", "--", "/container-server/sandbox"]

package/README.md

@@ -82,8 +82,12 @@ export default {
 
     // Execute Python code
     if (url.pathname === '/run') {
-      const result = await sandbox.exec('python3 -c "print(2 + 2)"');
-      return Response.json({ output: result.stdout, success: result.success });
+      const process = await sandbox.exec(['python3', '-c', 'print(2 + 2)']);
+      const output = await process.output({ encoding: 'utf8' });
+      return Response.json({
+        output: output.stdout,
+        success: output.exitCode === 0
+      });
     }
 
     // Work with files
@@ -98,6 +102,48 @@ export default {
 };
 ```
 
+## Process Execution
+
+A Sandbox is the long-running computer. `exec()` launches one supervised argv process and returns after the runtime confirms launch; it does not run through a hidden persistent shell.
+
+```ts
+const process = await sandbox.exec(['python3', '-c', 'print(2 + 2)']);
+const output = await process.output({ encoding: 'utf8' });
+
+console.log(process.id, process.pid, output.stdout, output.exitCode);
+```
+
+`await sandbox.exec(argv)` waits only for launch; `process.pid` is available once it resolves. `await process.output()` and `await process.waitForExit()` wait for completion. `process.status()` observes the current state, and `process.logs()` streams replayable cursor events incrementally.
+
+`output()` is replayable but may return `truncated: true`; use `logs({ since, replay, follow })` for cursor resume and output too large to buffer. `exec(argv, { timeout })` sets a remote process lifetime deadline: the supervisor may terminate and then kill the process internally, and completion is reported with `timedOut: true`. Timeouts and `AbortSignal`s on `logs()`, `output()`, `waitForExit()`, `waitForLog()`, and `waitForPort()` cancel only that local observation—they do not stop the process. Call `process.kill(signal)` with a numeric signal (default `15`) to request termination.
+
+Use explicit shell argv when you need shell syntax:
+
+```ts
+const proc = await sandbox.exec(['/bin/bash', '-lc', 'cd app && npm test'], {
+  cwd: '/workspace',
+  env: { CI: '1' }
+});
+```
+
+For asynchronous work, keep `proc.id` and recover the live process from a later Worker request:
+
+```ts
+const server = await sandbox.exec([
+  '/bin/bash',
+  '-lc',
+  'npm run dev -- --host 0.0.0.0'
+]);
+await server.waitForPort(3000);
+
+const recovered = await sandbox.getProcess(server.id);
+const running = await sandbox.listProcesses();
+```
+
+`getProcess()` and `listProcesses()` are non-waking discovery calls: with no active runtime they return `null` and `[]` instead of starting a replacement. Handles, IDs, PIDs, statuses, retained logs, and cursors belong to the runtime that launched the process. After sleep, restart, or replacement, discovery cannot recover them and operations on an old handle fail with `STALE_PROCESS_HANDLE` rather than targeting a replacement runtime.
+
+Use `createTerminal()` for a persistent interactive PTY shell with input, resize, interrupt, terminate, and reconnect semantics. Terminals remain separate from supervised processes and are also runtime-local.
+
 ## Quick tunnels
 
 `sandbox.tunnels.get(port)` exposes a service running inside the

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,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"}
+{"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;;;;AChFhB;AAOA;AAWC;AA6CD;EAA4C,cAAA,CAAA,EAAA,MAAA;EA2BH;;;;;EAiFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFtIT,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;;;;AChFpC;AAOA;AAmDU,iBDsBM,oBAAA,CCrBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFbxB,UE9CQ,cAAA,CF8CR;EACG;EAAO,UAAA,CAAA,EAAA,MAAA;EAYF;;;UEpDA,SAAA;EDgDD;EAyBA,IAAA,EAAA,MAAA;;;;EChFC,KAAA,EAAA,MAAA;EAOA;EAmDP,MAAA,EA3CA,QA2CW,CA3CF,cA4CR,CAAA;EAIE;EAA+B,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UALlC,WAAA,CAiHiC;EAUd,OAAA,EA1HlB,sBA0HkB;EAyBZ,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;AA/I0B,cAA9B,QAAA,SAAiB,aAAa,CAAC,WAAD,CAAA,CAAA;;;;ECM3B;EACN,QAAA,WAAA;EACC;EACQ,QAAA,kBAAA;EAAhB;EAAe,QAAA,iBAAA;;;;;;;;mCDkBuB;;;;;;sCA6CG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBAUd;WAyBZ;;;;;;;;;;;;;;;;;;;;;;;;AAvMjB;AAWC;AA6CD;;;;;;;;;;AA+IiB,iBCzID,MAAA,CDyIC,MAAA,ECxIP,cDwIO,EAAA,MAAA,CAAA,ECvIN,YDuIM,CAAA,ECtId,eDsIc,CCtIE,SDsIF,CAAA"}