Optimize Docker image size with lean and Python variants (#259)

* fix: exclude src and tsconfig from npm package

Add files field to package.json to explicitly list published files.
Fixes linting errors for users whose IDEs try to resolve the
workspace-only @repo/typescript-config reference in tsconfig.json.

* build: bundle sandbox-container with Bun

Replace tsc compilation with Bun.build() bundling. This inlines all
dependencies (@repo/shared, zod, async-mutex) into single files,
eliminating the need for node_modules in the container image.

* feat: transpile TypeScript in process-pool using Bun.Transpiler

Move TypeScript transpilation from the executor to process-pool.ts.
This allows us to use Bun's built-in transpiler (since process-pool
runs on Bun) and send plain JavaScript to the Node-based executor.

* refactor: consolidate JS and TS to single executor

TypeScript is now transpiled in process-pool.ts before execution,
so both JS and TS can use the same node_executor. This simplifies
the codebase and removes the need for the separate ts_executor.

* chore: remove esbuild dependency

esbuild is no longer needed since TypeScript transpilation now uses
Bun's built-in Bun.Transpiler instead.

* build: remove node_modules from Docker image

Use bundled output instead of copying node_modules. The container
server and JS executor are now self-contained bundles with all
dependencies inlined. Reduces image size by ~670MB.

* feat: add Python-not-available error for lean image

When PYTHON_POOL_MIN_SIZE=0, return a helpful error message directing
users to the -python image variant instead of failing cryptically.

* feat: add multi-target Dockerfile for image variants

- default: lean image without Python (~600-800MB)
- python: full image with Python + data science packages (~1.3GB)

Users can choose the appropriate variant based on their needs.
The default image is suitable for most use cases (shell commands,
file operations, JS/TS code interpreter). The python variant adds
Python code interpreter with matplotlib, numpy, pandas, ipython.

* build: update docker scripts to build both variants

docker:local, docker:publish, and docker:publish:beta now build
both the default and -python image variants.

* fix: proper Python detection and CI updates for image variants

- Python check now invokes python3 binary instead of checking env var
- E2E test-worker and integration Dockerfiles use -python variant
- CI workflows build python target for E2E tests
- Release workflow pushes both default and -python variants
- Remove unused docker:publish scripts (CI handles publishing)

* chore: add changeset for image optimization

* build: update pkg-pr-new workflow for image variants

Build and push both default and -python Docker image variants.
Update PR comment to show both image options.

* fix: check Python availability before reserving executor

Move Python availability check earlier in the flow so context creation
fails with a helpful error message before trying to spawn python3.

* test: add E2E test for base image Python error

Add E2E test validating the Python-not-available error message when
using the base image variant. Updates CI to build both image variants
and auto-regenerates wrangler.jsonc from template before E2E tests.

* chore: simplify changeset description

* Add PYTHON_NOT_AVAILABLE error code with proper HTTP 501 status

When Python is unavailable in the base image, the error now returns
HTTP 501 with the PYTHON_NOT_AVAILABLE error code instead of a generic
500 INTERNAL_ERROR. The interpreter service detects this specific error
and propagates the correct code through the error handling chain.

Also fixes an untyped array in ensureMinimumPool and strengthens the
changeset breaking change warning for Python users.

* Run JS tests on base image and use dynamic version in error message

JavaScript-only E2E tests now run against the base image to validate
the lean image works correctly for non-Python workloads. This provides
coverage for the bundled JS executor without requiring Python.

The Python unavailable error message now uses SANDBOX_VERSION env var
when available, falling back to <version> placeholder. This gives users
the exact version to use in production while keeping the placeholder
for development.

* Refactor container naming: base image default, Python explicit

- Rename SandboxBase → SandboxPython in test worker
- Flip header logic: X-Sandbox-Type: python selects Python image
- Default (no header) now uses base image (smaller, no Python)
- Update cleanup script for -python suffix
- Remove per-run CI cleanup (resources persist until PR closes)

* Fix Docker comment update to match plural 'Images'

* Fix Python unavailable test to expect 500 status

Author: ghostwriternr

.changeset/image-optimization.md

@@ -0,0 +1,22 @@
+---
+'@cloudflare/sandbox': minor
+---
+
+Add lean and Python image variants to reduce Docker image size
+
+**BREAKING CHANGE for Python users:** The default image no longer includes Python.
+
+- `cloudflare/sandbox:<version>` - lean image without Python (~600-800MB)
+- `cloudflare/sandbox:<version>-python` - full image with Python + data science packages (~1.3GB)
+
+**Migration:** If using `CodeInterpreter.runCode()` with Python, update your Dockerfile:
+
+```dockerfile
+# Before
+FROM cloudflare/sandbox:0.5.6
+
+# After
+FROM cloudflare/sandbox:0.5.6-python
+```
+
+Without this change, Python execution will fail with `PYTHON_NOT_AVAILABLE` error.

.github/workflows/pkg-pr-new.yml

@@ -77,18 +77,35 @@ jobs:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
-      - name: Build and push Docker image (preview)
+      - name: Build and push Docker image (default)
         uses: docker/build-push-action@v6
         with:
           context: .
           file: packages/sandbox/Dockerfile
+          target: default
           platforms: linux/amd64
           push: true
           tags: cloudflare/sandbox:${{ steps.package-version.outputs.version }}
           cache-from: |
-            type=gha,scope=preview-pr-${{ github.event.pull_request.number }}
-            type=gha,scope=release
-          cache-to: type=gha,mode=max,scope=preview-pr-${{ github.event.pull_request.number }}
+            type=gha,scope=preview-pr-${{ github.event.pull_request.number }}-default
+            type=gha,scope=release-default
+          cache-to: type=gha,mode=max,scope=preview-pr-${{ github.event.pull_request.number }}-default
+          build-args: |
+            SANDBOX_VERSION=${{ steps.package-version.outputs.version }}
+
+      - name: Build and push Docker image (python)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: packages/sandbox/Dockerfile
+          target: python
+          platforms: linux/amd64
+          push: true
+          tags: cloudflare/sandbox:${{ steps.package-version.outputs.version }}-python
+          cache-from: |
+            type=gha,scope=preview-pr-${{ github.event.pull_request.number }}-python
+            type=gha,scope=release-python
+          cache-to: type=gha,mode=max,scope=preview-pr-${{ github.event.pull_request.number }}-python
           build-args: |
             SANDBOX_VERSION=${{ steps.package-version.outputs.version }}
 
@@ -100,8 +117,9 @@ jobs:
         with:
           script: |
             const version = '${{ steps.package-version.outputs.version }}';
-            const dockerTag = `cloudflare/sandbox:${version}`;
-            const body = `### 🐳 Docker Image Published\n\n\`\`\`dockerfile\nFROM ${dockerTag}\n\`\`\`\n\n**Version:** \`${version}\`\n\nYou can use this Docker image with the preview package from this PR.`;
+            const defaultTag = `cloudflare/sandbox:${version}`;
+            const pythonTag = `cloudflare/sandbox:${version}-python`;
+            const body = `### 🐳 Docker Images Published\n\n**Default (no Python):**\n\`\`\`dockerfile\nFROM ${defaultTag}\n\`\`\`\n\n**With Python:**\n\`\`\`dockerfile\nFROM ${pythonTag}\n\`\`\`\n\n**Version:** \`${version}\`\n\nUse the \`-python\` variant if you need Python code execution.`;
 
             // Find existing comment
             const { data: comments } = await github.rest.issues.listComments({
@@ -112,7 +130,7 @@ jobs:
 
             const botComment = comments.find(comment =>
               comment.user.type === 'Bot' &&
-              comment.body.includes('Docker Image Published')
+              comment.body.includes('Docker Images Published')
             );
 
             if (botComment) {

.github/workflows/pullrequest.yml

@@ -116,16 +116,15 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Build test worker Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: packages/sandbox/Dockerfile
-          platforms: linux/amd64 # Explicit single-arch for compatibility with release-amd64 cache
-          load: true # Load into Docker daemon for local testing
-          tags: cloudflare/sandbox-test:${{ needs.unit-tests.outputs.version || '0.0.0' }}
-          build-args: |
-            SANDBOX_VERSION=${{ needs.unit-tests.outputs.version || '0.0.0' }}
+      - name: Build test worker Docker images (base + python)
+        run: |
+          VERSION=${{ needs.unit-tests.outputs.version || '0.0.0' }}
+          # Build base image (no Python) - used by SandboxBase binding
+          docker build -f packages/sandbox/Dockerfile --target default --platform linux/amd64 \
+            --build-arg SANDBOX_VERSION=$VERSION -t cloudflare/sandbox-test:$VERSION .
+          # Build python image - used by Sandbox binding
+          docker build -f packages/sandbox/Dockerfile --target python --platform linux/amd64 \
+            --build-arg SANDBOX_VERSION=$VERSION -t cloudflare/sandbox-test:$VERSION-python .
 
       # Deploy test worker using official Cloudflare action
       - name: Deploy test worker
@@ -161,16 +160,10 @@ jobs:
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 
-      # Cleanup: Delete test worker and container (only for PR environments)
-      - name: Cleanup test deployment
-        if: always() && github.event_name == 'pull_request'
-        continue-on-error: true
-        run: |
-          cd tests/e2e/test-worker
-          ../../../scripts/cleanup-test-deployment.sh ${{ steps.env-name.outputs.worker_name }}
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      # Note: Resources are NOT cleaned up after each run to speed up subsequent CI runs.
+      # Cleanup happens via:
+      # - cleanup.yml: Triggered when PR is closed
+      # - cleanup-stale.yml: Daily cron job for orphaned/stale resources
 
   # Validate changesets don't contain internal packages
   validate-changesets:

.github/workflows/release.yml

@@ -109,9 +109,10 @@ jobs:
         with:
           context: .
           file: packages/sandbox/Dockerfile
+          target: python # E2E tests require Python for code interpreter tests
           platforms: linux/amd64
           load: true
-          tags: cloudflare/sandbox-test:${{ needs.unit-tests.outputs.version }}
+          tags: cloudflare/sandbox-test:${{ needs.unit-tests.outputs.version }}-python
           build-args: |
             SANDBOX_VERSION=${{ needs.unit-tests.outputs.version }}
 
@@ -177,16 +178,31 @@ jobs:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
-      - name: Build and push Docker image
+      - name: Build and push Docker image (default)
         uses: docker/build-push-action@v6
         with:
           context: .
           file: packages/sandbox/Dockerfile
+          target: default
           platforms: linux/amd64
           push: true
           tags: cloudflare/sandbox:${{ needs.unit-tests.outputs.version }}
-          cache-from: type=gha,scope=release
-          cache-to: type=gha,mode=max,scope=release
+          cache-from: type=gha,scope=release-default
+          cache-to: type=gha,mode=max,scope=release-default
+          build-args: |
+            SANDBOX_VERSION=${{ needs.unit-tests.outputs.version }}
+
+      - name: Build and push Docker image (python)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: packages/sandbox/Dockerfile
+          target: python
+          platforms: linux/amd64
+          push: true
+          tags: cloudflare/sandbox:${{ needs.unit-tests.outputs.version }}-python
+          cache-from: type=gha,scope=release-python
+          cache-to: type=gha,mode=max,scope=release-python
           build-args: |
             SANDBOX_VERSION=${{ needs.unit-tests.outputs.version }}