Optimize Docker image size with lean and Python variants #259
Conversation
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.
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.
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.
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.
esbuild is no longer needed since TypeScript transpilation now uses Bun's built-in Bun.Transpiler instead.
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.
When PYTHON_POOL_MIN_SIZE=0, return a helpful error message directing users to the -python image variant instead of failing cryptically.
- 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.
docker:local, docker:publish, and docker:publish:beta now build both the default and -python 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)
Build and push both default and -python Docker image variants. Update PR comment to show both image options.
Move Python availability check earlier in the flow so context creation fails with a helpful error message before trying to spawn python3.
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.
🦋 Changeset detectedLatest commit: 4b1d4ac The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
commit: |
🐳 Docker Images PublishedDefault (no Python): FROM cloudflare/sandbox:0.0.0-pr-259-461d29bWith Python: FROM cloudflare/sandbox:0.0.0-pr-259-461d29b-pythonVersion: Use the |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
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.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add documentation for lean and Python image variants introduced in cloudflare/sandbox-sdk#259. This breaking change splits the base image into two variants optimized for different workloads. - Document default (lean) image without Python (~600-800MB) - Document Python image with data science packages (~1.3GB) - Add migration guide for users upgrading from 0.5.5 to 0.5.6+ - Document PYTHON_NOT_AVAILABLE error and how to resolve it - Update all Dockerfile examples to use 0.5.6 versions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
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.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
- 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)
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Sync documentation for sandbox-sdk PR #259: Optimize Docker image size with lean and Python variants. Changes: - Update Dockerfile reference with two image variants (lean and python) - Add Python requirement warning to Code Interpreter documentation - Create migration guide for upgrading to 0.5.6+ with image variants - Include size comparison table and use case recommendations Breaking change: Default image no longer includes Python. Users running Python code must update to use the -python image variant. Related: cloudflare/sandbox-sdk#259 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Claude Code Review
Strong PR - achieves the 62% size reduction goal with sound bundling architecture. However, three critical issues must be fixed before merge.
Critical Issues
1. HTTP status code mismatch
PYTHON_NOT_AVAILABLE is mapped to 501 (Not Implemented) in status-map.ts:51, but the test worker returns 500 for all errors. The test at line 909 expects 500, masking the proper semantic status.
Impact: Clients can't distinguish feature unavailability (501) from server errors (500).
Fix: Update test worker error handling to use proper HTTP status codes from error mappings.
2. No startup validation for bundled executors
Container spawns executors at hardcoded paths (/container-server/dist/runtime/executors/...) without verifying files exist. If bundling fails, container starts successfully but crashes cryptically at runtime.
Fix: Add existence checks during startup for all bundled executors (fail-fast with clear error).
3. E2E test coverage gap for lean image
CI builds both variants but release.yml:112 only tests Python image (target: python). The lean image's bundled JavaScript executor is never validated in E2E.
Fix: Add E2E test job that deploys and tests the lean image variant.
Architecture Observations
Python detection (process-pool.ts:12): 5-second timeout for python3 --version is excessive. Consider reducing to 1000ms - version checks should be near-instantaneous.
Multi-stage Dockerfile: Excellent architecture. Proper layer caching, shared runtime-base, and clean separation of variants.
Bundling strategy: Correct use of Bun.build() with appropriate targets (bun for server, node for executor).
Overall Verdict
Needs fixes - address the three critical issues above. Once resolved, this is ready to merge.
Strengths: Image size goals achieved, breaking change properly documented for beta, version sync maintained, error messages helpful.
Sync documentation for PR #259: Optimize Docker image size with lean and Python variants Changes: - Add documentation for two image variants (default and -python) - Include breaking change notice for Python users - Add migration guide from v0.5.x to v0.6.0+ - Document PYTHON_NOT_AVAILABLE error behavior - Update all examples to show appropriate image selection - Clarify Python availability requirements in Code Interpreter API Related upstream PR: cloudflare/sandbox-sdk#259
2 participants
Summary
cloudflare/sandbox:<version>(lean, 617 MB) andcloudflare/sandbox:<version>-python(full, 1.22 GB)Size comparison with current 0.5.6 release (1.64 GB):
Closes #14
Closes #169
Changes
Image Size Optimization
sandbox-containerserver with Bun.build() (~185KB bundled)Image Variants
runtime-base,default,python)defaulttarget: Lean image without Python for shell/JS workloadspythontarget: Full image with Python 3.11 + data science packagesDeveloper Experience
Test Plan