Add standalone binary for arbitrary Dockerfile support (#280)

* Add standalone binary for arbitrary Dockerfile support

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.

* Move binary to /container-server/sandbox

* Add --platform flag to docker create commands

* Fix signal handling and refactor server lifecycle

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.

* Switch base images from Alpine to glibc for binary compat

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.

* Add E2E tests for standalone binary pattern

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.

* Document standalone binary pattern and dependencies

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.

* Add CMD passthrough docs and release checksums

Document the supervisor lifecycle model for standalone binary users.
Add SHA256 checksum generation for binary releases.

Author: ghostwriternr

.changeset/standalone-binary-arbitrary-dockerfile.md

@@ -0,0 +1,21 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Add standalone binary support for arbitrary Dockerfiles
+
+Users can now add sandbox capabilities to any Docker image:
+
+```dockerfile
+FROM your-image:tag
+
+COPY --from=cloudflare/sandbox:VERSION /container-server/sandbox /sandbox
+ENTRYPOINT ["/sandbox"]
+
+# Optional: run your own startup command
+CMD ["/your-entrypoint.sh"]
+```
+
+The `/sandbox` binary starts the HTTP API server, then executes any CMD as a child process with signal forwarding.
+
+Includes backwards compatibility for existing custom startup scripts.

.github/templates/pr-preview-comment.md

@@ -0,0 +1,46 @@
+### 🐳 Docker Images Published
+
+**Default:**
+
+```dockerfile
+FROM {{DEFAULT_TAG}}
+```
+
+**With Python:**
+
+```dockerfile
+FROM {{PYTHON_TAG}}
+```
+
+**With OpenCode:**
+
+```dockerfile
+FROM {{OPENCODE_TAG}}
+```
+
+**Version:** `{{VERSION}}`
+
+Use the `-python` variant if you need Python code execution, or `-opencode` for the variant with OpenCode AI coding agent pre-installed.
+
+---
+
+### 📦 Standalone Binary
+
+**For arbitrary Dockerfiles:**
+
+```dockerfile
+COPY --from={{DEFAULT_TAG}} /container-server/sandbox /sandbox
+ENTRYPOINT ["/sandbox"]
+```
+
+**Download via GitHub CLI:**
+
+```bash
+gh run download {{RUN_ID}} -n sandbox-binary
+```
+
+**Extract from Docker:**
+
+```bash
+docker run --rm {{DEFAULT_TAG}} cat /container-server/sandbox > sandbox && chmod +x sandbox
+```

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

@@ -125,18 +125,42 @@ jobs:
           build-args: |
             SANDBOX_VERSION=${{ steps.package-version.outputs.version }}
 
+      - name: Extract standalone binary from Docker image
+        run: |
+          VERSION=${{ steps.package-version.outputs.version }}
+          CONTAINER_ID=$(docker create --platform linux/amd64 cloudflare/sandbox:$VERSION)
+          docker cp $CONTAINER_ID:/container-server/sandbox ./sandbox-linux-x64
+          docker rm $CONTAINER_ID
+          chmod +x ./sandbox-linux-x64
+
+      - name: Upload standalone binary as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sandbox-binary
+          path: ./sandbox-linux-x64
+          retention-days: 30
+
       - name: Publish to pkg.pr.new
         run: npx pkg-pr-new publish './packages/sandbox'
 
       - name: Comment Docker image tag
         uses: actions/github-script@v7
         with:
           script: |
+            const fs = require('fs');
             const version = '${{ steps.package-version.outputs.version }}';
+            const runId = '${{ github.run_id }}';
             const defaultTag = `cloudflare/sandbox:${version}`;
             const pythonTag = `cloudflare/sandbox:${version}-python`;
             const opencodeTag = `cloudflare/sandbox:${version}-opencode`;
-            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**With OpenCode:**\n\`\`\`dockerfile\nFROM ${opencodeTag}\n\`\`\`\n\n**Version:** \`${version}\`\n\nUse the \`-python\` variant for Python code execution, or \`-opencode\` for the OpenCode AI coding agent.`;
+
+            const template = fs.readFileSync('.github/templates/pr-preview-comment.md', 'utf8');
+            const body = template
+              .replace(/\{\{VERSION\}\}/g, version)
+              .replace(/\{\{RUN_ID\}\}/g, runId)
+              .replace(/\{\{DEFAULT_TAG\}\}/g, defaultTag)
+              .replace(/\{\{PYTHON_TAG\}\}/g, pythonTag)
+              .replace(/\{\{OPENCODE_TAG\}\}/g, opencodeTag);
 
             // Find existing comment
             const { data: comments } = await github.rest.issues.listComments({

.github/workflows/pullrequest.yml

@@ -116,7 +116,7 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Build test worker Docker images (base + python + opencode)
+      - name: Build test worker Docker images (base + python + opencode + standalone)
         run: |
           VERSION=${{ needs.unit-tests.outputs.version || '0.0.0' }}
           # Build base image (no Python) - used by Sandbox binding
@@ -128,6 +128,16 @@ jobs:
           # Build opencode image - used by SandboxOpencode binding
           docker build -f packages/sandbox/Dockerfile --target opencode --platform linux/amd64 \
             --build-arg SANDBOX_VERSION=$VERSION -t cloudflare/sandbox-test:$VERSION-opencode .
+          # Build standalone image (arbitrary base with binary) - used by SandboxStandalone binding
+          # Use regex to replace any version number, avoiding hardcoded version mismatch
+          # Build from test-worker directory so COPY startup-test.sh works
+          cd tests/e2e/test-worker
+          sed -E "s|cloudflare/sandbox-test:[0-9]+\.[0-9]+\.[0-9]+|cloudflare/sandbox-test:$VERSION|g" \
+            Dockerfile.standalone > Dockerfile.standalone.tmp
+          docker build -f Dockerfile.standalone.tmp --platform linux/amd64 \
+            -t cloudflare/sandbox-test:$VERSION-standalone .
+          rm Dockerfile.standalone.tmp
+          cd ../../..
 
       # Deploy test worker using official Cloudflare action
       - name: Deploy test worker

.github/workflows/release.yml

@@ -108,7 +108,7 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Build test worker Docker images (base + python + opencode)
+      - name: Build test worker Docker images (base + python + opencode + standalone)
         run: |
           VERSION=${{ needs.unit-tests.outputs.version }}
           # Build base image (no Python) - used by Sandbox binding
@@ -120,6 +120,16 @@ jobs:
           # Build opencode image - used by SandboxOpencode binding
           docker build -f packages/sandbox/Dockerfile --target opencode --platform linux/amd64 \
             --build-arg SANDBOX_VERSION=$VERSION -t cloudflare/sandbox-test:$VERSION-opencode .
+          # Build standalone image (arbitrary base with binary) - used by SandboxStandalone binding
+          # Use regex to replace any version number, avoiding hardcoded version mismatch
+          # Build from test-worker directory so COPY startup-test.sh works
+          cd tests/e2e/test-worker
+          sed -E "s|cloudflare/sandbox-test:[0-9]+\.[0-9]+\.[0-9]+|cloudflare/sandbox-test:$VERSION|g" \
+            Dockerfile.standalone > Dockerfile.standalone.tmp
+          docker build -f Dockerfile.standalone.tmp --platform linux/amd64 \
+            -t cloudflare/sandbox-test:$VERSION-standalone .
+          rm Dockerfile.standalone.tmp
+          cd ../../..
 
       - name: Deploy test worker
         uses: cloudflare/wrangler-action@v3
@@ -230,6 +240,15 @@ jobs:
           build-args: |
             SANDBOX_VERSION=${{ needs.unit-tests.outputs.version }}
 
+      - name: Extract standalone binary from Docker image
+        run: |
+          VERSION=${{ needs.unit-tests.outputs.version }}
+          CONTAINER_ID=$(docker create --platform linux/amd64 cloudflare/sandbox:$VERSION)
+          docker cp $CONTAINER_ID:/container-server/sandbox ./sandbox-linux-x64
+          docker rm $CONTAINER_ID
+          file ./sandbox-linux-x64
+          ls -la ./sandbox-linux-x64
+
       - id: changesets
         uses: changesets/action@v1
         with:
@@ -238,3 +257,13 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_CONFIG_PROVENANCE: true
+
+      - name: Upload standalone binary to GitHub release
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=${{ needs.unit-tests.outputs.version }}
+          sha256sum sandbox-linux-x64 > sandbox-linux-x64.sha256
+          # Tag format matches changesets: @cloudflare/sandbox@VERSION
+          gh release upload "@cloudflare/sandbox@${VERSION}" ./sandbox-linux-x64 ./sandbox-linux-x64.sha256 --clobber

docs/STANDALONE_BINARY.md

@@ -0,0 +1,55 @@
+# Standalone Binary Pattern
+
+Add Cloudflare Sandbox capabilities to any Docker image by copying the `/sandbox` binary.
+
+## Basic Usage
+
+```dockerfile
+FROM node:20-slim
+
+# Required: install 'file' for SDK file operations
+RUN apt-get update && apt-get install -y --no-install-recommends file \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=cloudflare/sandbox:latest /container-server/sandbox /sandbox
+
+ENTRYPOINT ["/sandbox"]
+CMD ["/your-startup-script.sh"]  # Optional: runs after server starts
+```
+
+## How CMD Passthrough Works
+
+The `/sandbox` binary acts as a supervisor:
+
+1. Starts HTTP API server on port 3000
+2. Spawns your CMD as a child process
+3. Forwards SIGTERM/SIGINT to the child
+4. If CMD exits 0, server keeps running; non-zero exits terminate the container
+
+## Required Dependencies
+
+| Dependency | Required For                                    | Install Command        |
+| ---------- | ----------------------------------------------- | ---------------------- |
+| `file`     | `readFile()`, `writeFile()`, any file operation | `apt-get install file` |
+| `git`      | `gitCheckout()`, `listBranches()`               | `apt-get install git`  |
+| `bash`     | Everything (core requirement)                   | Usually pre-installed  |
+
+Most base images (node:slim, python:slim, ubuntu) include everything except `file` and `git`.
+
+## What Works Without Extra Dependencies
+
+- `exec()` - Run shell commands
+- `startProcess()` - Background processes
+- `exposePort()` - Expose services
+
+## Troubleshooting
+
+**"Failed to detect MIME type"** - Install `file`
+
+**"git: command not found"** - Install `git` (only needed for git operations)
+
+**Commands hang** - Ensure `bash` exists at `/bin/bash`
+
+## Note on Code Interpreter
+
+`runCode()` requires Python/Node executors not included in the standalone binary. Use the official sandbox images for code interpreter support.

packages/sandbox-container/build.ts

@@ -1,39 +1,44 @@
 /**
  * Build script for sandbox-container using Bun's bundler.
- * Bundles the container server and JS executor into standalone files.
+ * Produces:
+ * - dist/sandbox: Standalone binary for /sandbox entrypoint
+ * - dist/index.js: Legacy JS bundle for backwards compatibility
+ * - dist/runtime/executors/javascript/node_executor.js: JS executor
  */
 
 import { mkdir } from 'node:fs/promises';
 
 // Ensure output directories exist
 await mkdir('dist/runtime/executors/javascript', { recursive: true });
 
-console.log('Building container server bundle...');
+// Build legacy JS bundle for backwards compatibility
+// Users with custom startup scripts that call `bun /container-server/dist/index.js` need this
+console.log('Building legacy JS bundle...');
 
-// Bundle the main container server
-const serverResult = await Bun.build({
-  entrypoints: ['src/index.ts'],
+const legacyResult = await Bun.build({
+  entrypoints: ['src/legacy.ts'],
   outdir: 'dist',
   target: 'bun',
   minify: true,
-  sourcemap: 'external'
+  sourcemap: 'external',
+  naming: 'index.js'
 });
 
-if (!serverResult.success) {
-  console.error('Server build failed:');
-  for (const log of serverResult.logs) {
+if (!legacyResult.success) {
+  console.error('Legacy bundle build failed:');
+  for (const log of legacyResult.logs) {
     console.error(log);
   }
   process.exit(1);
 }
 
 console.log(
-  `  dist/index.js (${(serverResult.outputs[0].size / 1024).toFixed(1)} KB)`
+  `  dist/index.js (${(legacyResult.outputs[0].size / 1024).toFixed(1)} KB)`
 );
 
 console.log('Building JavaScript executor...');
 
-// Bundle the JS executor (runs on Node, not Bun)
+// Bundle the JS executor (runs on Node or Bun for code interpreter)
 const executorResult = await Bun.build({
   entrypoints: ['src/runtime/executors/javascript/node_executor.ts'],
   outdir: 'dist/runtime/executors/javascript',
@@ -54,4 +59,34 @@ console.log(
   `  dist/runtime/executors/javascript/node_executor.js (${(executorResult.outputs[0].size / 1024).toFixed(1)} KB)`
 );
 
+console.log('Building standalone binary...');
+
+// Compile standalone binary (bundles Bun runtime)
+const proc = Bun.spawn(
+  [
+    'bun',
+    'build',
+    'src/main.ts',
+    '--compile',
+    '--target=bun-linux-x64',
+    '--outfile=dist/sandbox',
+    '--minify'
+  ],
+  {
+    cwd: process.cwd(),
+    stdio: ['inherit', 'inherit', 'inherit']
+  }
+);
+
+const exitCode = await proc.exited;
+if (exitCode !== 0) {
+  console.error('Standalone binary build failed');
+  process.exit(1);
+}
+
+// Get file size
+const file = Bun.file('dist/sandbox');
+const size = file.size;
+console.log(`  dist/sandbox (${(size / 1024 / 1024).toFixed(1)} MB)`);
+
 console.log('Build complete!');