Create multi-platform Docker image and switch to Cloudflare official repo (#29)

* Add Docker multi-architecture build system

- Replace manual arch-specific builds with buildx multi-arch
- Add GitHub Actions workflow for automated Docker builds
- Update documentation to use unified Docker image
- Create test workflow to validate multi-arch builds

* Fix bun installation

* Fix container startup race condition

- Add defaultPort = 3000 to Sandbox class for proper port readiness
checks
- Fix onStop() to only log shutdown when container is actually stopped
- Add ping() method that checks container state without triggering
containerFetch
- Update /api/ping endpoint to use new ping() method instead of exec()

This prevents the "Sandbox successfully shut down" message from
appearing during initialization and fixes port exposure errors on
first run.

* Override containerFetch to handle failures

* Handle 503s during startup

* Revert HTTPClient

* Use local docker image in local dev

* Remove plan

* Switch over to Cloudflare official repo

* Document setEnvVars

* Add changeset

Author: ghostwriternr

.changeset/icy-garlics-tan.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+Create multi-platform Docker image and switch to Cloudflare official repo

.github/changeset-version.ts

@@ -1,4 +1,5 @@
 import { execSync } from "node:child_process";
+import * as fs from "node:fs";
 
 // This script is used by the `release.yml` workflow to update the version of the packages being released.
 // The standard step is only to run `changeset version` but this does not update the package-lock.json file.
@@ -11,3 +12,44 @@ execSync("npx changeset version", {
 execSync("npm install", {
   stdio: "inherit",
 });
+
+// Update Dockerfile and README version references after changeset updates package.json
+try {
+  const packageJson = JSON.parse(fs.readFileSync("./packages/sandbox/package.json", "utf-8"));
+  const newVersion = packageJson.version;
+
+  const dockerfilePath = "./examples/basic/Dockerfile";
+  let dockerfileContent = fs.readFileSync(dockerfilePath, "utf-8");
+
+  // Update the production image version in the comment
+  dockerfileContent = dockerfileContent.replace(
+    /# FROM docker\.io\/cloudflare\/sandbox:[\d.]+/,
+    `# FROM docker.io/cloudflare/sandbox:${newVersion}`
+  );
+
+  // Update the test image version
+  dockerfileContent = dockerfileContent.replace(
+    /FROM cloudflare\/sandbox-test:[\d.]+/,
+    `FROM cloudflare/sandbox-test:${newVersion}`
+  );
+
+  fs.writeFileSync(dockerfilePath, dockerfileContent);
+  console.log(`✅ Updated Dockerfile versions to ${newVersion}`);
+
+  // Update README.md
+  const readmePath = "./README.md";
+  let readmeContent = fs.readFileSync(readmePath, "utf-8");
+
+  // Update the Docker image version in README
+  readmeContent = readmeContent.replace(
+    /FROM docker\.io\/cloudflare\/sandbox:[\d.]+/,
+    `FROM docker.io/cloudflare/sandbox:${newVersion}`
+  );
+
+  fs.writeFileSync(readmePath, readmeContent);
+  console.log(`✅ Updated README.md version to ${newVersion}`);
+
+} catch (error) {
+  console.error("❌ Failed to update file versions:", error);
+  // Don't fail the whole release for this
+}

.github/workflows/prerelease.yml

@@ -33,6 +33,18 @@ jobs:
       - run: npm run check
       - run: CI=true npm run test
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
+
+      - name: Build and push Docker image (beta)
+        run: npm run docker:publish:beta --workspace=@cloudflare/sandbox
+
       - run: npm publish --tag beta --access public
         env:
           NPM_PUBLISH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/release.yml

@@ -27,6 +27,18 @@ jobs:
       - run: npm install
       - run: npm run build
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
+
+      - name: Build and push Docker image
+        run: npm run docker:publish --workspace=@cloudflare/sandbox
+
       - id: changesets
         uses: changesets/action@v1
         with:

README.md

@@ -64,9 +64,7 @@ npm install @cloudflare/sandbox
 1. **Create a Dockerfile** (temporary requirement, will be removed in future releases):
 
 ```dockerfile
-FROM docker.io/ghostwriternr/cloudflare-sandbox:0.0.9
-# If building your project on arm64, use:
-# FROM docker.io/ghostwriternr/cloudflare-sandbox-arm:0.0.9
+FROM docker.io/cloudflare/sandbox:0.0.9
 
 EXPOSE 3000
 
@@ -203,6 +201,28 @@ await sandbox.gitCheckout("https://github.com/user/repo", {
 });
 ```
 
+#### `setEnvVars(envVars)`
+
+Set environment variables dynamically in the sandbox.
+
+> **Important**: This method must be called immediately after `getSandbox()` and before any other operations. Once a sandbox instance starts up, environment variables cannot be changed
+for that instance.
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, "my-sandbox");
+
+// Set environment variables FIRST, before any other operations
+await sandbox.setEnvVars({
+  NODE_ENV: "production",
+  API_KEY: "your-api-key",
+  DATABASE_URL: "postgresql://localhost:5432/mydb"
+});
+
+// Now you can run commands - environment variables are available
+const result = await sandbox.exec("echo $NODE_ENV");
+console.log(result.stdout); // "production"
+```
+
 #### Process Management
 
 - `listProcesses()` - List all running processes

examples/basic/Dockerfile

@@ -1,4 +1,8 @@
-FROM docker.io/ghostwriternr/cloudflare-sandbox:0.0.9
+# This image is unique to this repo, and you'll never need it.
+# Whenever you're integrating with sandbox SDK in your own project,
+# you should use the official image instead:
+# FROM docker.io/cloudflare/sandbox:0.1.1
+FROM cloudflare/sandbox-test:0.1.1
 
 EXPOSE 8080
 EXPOSE 3001

examples/basic/wrangler.jsonc

@@ -33,5 +33,8 @@
       "new_sqlite_classes": ["Sandbox"],
       "tag": "v1"
     }
-  ]
+  ],
+  "dev": {
+    "container_engine": "unix:///Users/naresh/.colima/default/docker.sock"
+  }
 }

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "typecheck": "tsx scripts/typecheck.ts",
     "check": "biome check && npm run typecheck",
-    "build": "npm run build -w @cloudflare/sandbox",
+    "build": "npm run build -w @cloudflare/sandbox && npm run docker:local -w @cloudflare/sandbox",
     "test": "echo 'No tests'",
     "toc": "doctoc README.md --github --maxlevel 3 && node scripts/fix-toc-links.js"
   },

packages/sandbox/Dockerfile

@@ -1,4 +1,5 @@
 # Sandbox base image with development tools, Python, Node.js, and Bun
+FROM oven/bun:latest AS bun-source
 FROM ubuntu:22.04
 
 # Prevent interactive prompts during package installation
@@ -50,11 +51,9 @@ RUN apt-get update && apt-get install -y ca-certificates curl gnupg \
     && apt-get install -y nodejs \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Bun using the official installation script
-RUN curl -fsSL https://bun.sh/install | bash \
-    && mv /root/.bun/bin/bun /usr/local/bin/bun \
-    && mv /root/.bun/bin/bunx /usr/local/bin/bunx \
-    && rm -rf /root/.bun
+# Install Bun from official image (avoids architecture compatibility issues)
+COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
+COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
 
 # Install global npm packages as root
 RUN npm install -g yarn pnpm

packages/sandbox/package.json

@@ -18,8 +18,9 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsup src/*.ts --outDir dist --dts --sourcemap --format esm",
-    "docker:build": "docker build -t ghostwriternr/cloudflare-sandbox:$npm_package_version .",
-    "docker:publish": "docker push docker.io/ghostwriternr/cloudflare-sandbox:$npm_package_version"
+    "docker:local": "docker build . -t cloudflare/sandbox-test:$npm_package_version",
+    "docker:publish": "docker buildx build --platform linux/amd64,linux/arm64 -t cloudflare/sandbox:$npm_package_version --push .",
+    "docker:publish:beta": "docker buildx build --platform linux/amd64,linux/arm64 -t cloudflare/sandbox:$npm_package_version-beta --push ."
   },
   "exports": {
     ".": {