Add standalone binary for arbitrary Dockerfile support #280
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Compiles sandbox-container to a self-contained binary at /sandbox that can be copied into any Docker image. Includes backwards compatibility for existing startup scripts via legacy JS bundle.
🦋 Changeset detectedLatest commit: ef9e2ac 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 |
agents-git-bot bot
pushed a commit
to cloudflare/cloudflare-docs
that referenced
this pull request
Dec 5, 2025
Documents the new standalone binary feature that allows users to add sandbox capabilities to any Docker image by copying the /sandbox binary. Updates include: - New section on using standalone binary with arbitrary base images - Examples for Python, Node.js, and Go base images - Explanation of how the binary works with signal forwarding - Mark existing startup script pattern as legacy for backwards compatibility - Update multiple services example to work with new binary Related to cloudflare/sandbox-sdk#280 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
3 tasks
commit: |
Contributor
🐳 Docker Images PublishedDefault: FROM cloudflare/sandbox:0.0.0-pr-280-916fff2With Python: FROM cloudflare/sandbox:0.0.0-pr-280-916fff2-pythonWith OpenCode: FROM cloudflare/sandbox:0.0.0-pr-280-916fff2-opencodeVersion: Use the 📦 Standalone BinaryFor arbitrary Dockerfiles: COPY --from=cloudflare/sandbox:0.0.0-pr-280-916fff2 /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]Download via GitHub CLI: gh run download 20118882350 -n sandbox-binaryExtract from Docker: docker run --rm cloudflare/sandbox:0.0.0-pr-280-916fff2 cat /container-server/sandbox > sandbox && chmod +x sandbox |
![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.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
agents-git-bot bot
pushed a commit
to cloudflare/cloudflare-docs
that referenced
this pull request
Dec 10, 2025
Documents the new /sandbox binary that enables adding sandbox capabilities to any Docker image without extending the Cloudflare base image. Includes: - Basic usage with COPY --from pattern - CMD passthrough with signal forwarding - Three methods to access the binary (Docker COPY, GitHub releases, docker extract) - Guidance on when to use standalone binary vs base image - Updated custom startup scripts to use new recommended approach - Backwards compatibility notes for existing users Updates websocket-connections guide to use new CMD-based startup approach instead of legacy exec bun pattern. Related to cloudflare/sandbox-sdk#280 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Signal handlers are now registered before spawning the child process to close a race window. Exit codes use os.constants.signals for correct Unix convention mapping. Server cleanup is returned from startServer() rather than relying on module-level state, making the dependency between server startup and shutdown handlers explicit.
The standalone binary compiled on glibc won't run on Alpine (musl). Using node:20-slim and oven/bun:1 ensures the binary works on standard Linux distributions like Debian, Ubuntu, and RHEL.
Tests that the sandbox binary works when copied into arbitrary Docker images. Validates command execution, file operations with MIME type detection, and CMD passthrough to user startup scripts.
Documents how to add sandbox capabilities to arbitrary Docker images by copying the /sandbox binary. Lists required dependencies (file, git) and what works without extra packages.
ghostwriternr
force-pushed
the
base-image
branch
from
a9108c4 to
8a35b58
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Document the supervisor lifecycle model for standalone binary users. Add SHA256 checksum generation for binary releases.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Compiles sandbox-container to a self-contained binary at
/container-server/sandboxthat can be copied into any Docker image.Fixes #269
Usage:
Alternative binary access:
Changes:
bun build --compile