cloudflare · ghostwriternr · Jan 14, 2026 · Jan 14, 2026
diff --git a/.changeset/add-cloudflare-ai-gateway-support.md b/.changeset/add-cloudflare-ai-gateway-support.md
diff --git a/.changeset/custom-port-tokens.md b/.changeset/custom-port-tokens.md
diff --git a/.changeset/fix-undefined-env-vars.md b/.changeset/fix-undefined-env-vars.md
diff --git a/examples/claude-code/Dockerfile b/examples/claude-code/Dockerfile
@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.11
+FROM docker.io/cloudflare/sandbox:0.7.0
 RUN npm install -g @anthropic-ai/claude-code
 ENV COMMAND_TIMEOUT_MS=300000
 EXPOSE 3000
diff --git a/examples/code-interpreter/Dockerfile b/examples/code-interpreter/Dockerfile
@@ -1 +1 @@
-FROM docker.io/cloudflare/sandbox:0.6.11-python
+FROM docker.io/cloudflare/sandbox:0.7.0-python
diff --git a/examples/minimal/Dockerfile b/examples/minimal/Dockerfile
@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.11
+FROM docker.io/cloudflare/sandbox:0.7.0
 
 # Required during local development to access exposed ports
 EXPOSE 8080
diff --git a/examples/openai-agents/Dockerfile b/examples/openai-agents/Dockerfile
@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.11
+FROM docker.io/cloudflare/sandbox:0.7.0
 
 # Required during local development to access exposed ports
 EXPOSE 8080

diff --git a/examples/opencode/Dockerfile b/examples/opencode/Dockerfile
@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.11
+FROM docker.io/cloudflare/sandbox:0.7.0
 
 # Add opencode install location to PATH before installation
 ENV PATH="/root/.opencode/bin:${PATH}"

diff --git a/examples/typescript-validator/Dockerfile b/examples/typescript-validator/Dockerfile
@@ -1,5 +1,5 @@
 # Use Cloudflare sandbox as base
-FROM docker.io/cloudflare/sandbox:0.6.11
+FROM docker.io/cloudflare/sandbox:0.7.0
 
 # Install esbuild for TypeScript bundling
 RUN npm install -g esbuild

diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/sandbox/CHANGELOG.md b/packages/sandbox/CHANGELOG.md
@@ -1,5 +1,56 @@
 # @cloudflare/sandbox
 
+## 0.7.0
+
+### Minor Changes
+
+- [#329](https://github.com/cloudflare/sandbox-sdk/pull/329) [`fc1a8ea`](https://github.com/cloudflare/sandbox-sdk/commit/fc1a8ea29cd1fe872ce1c08eabca083601aae5c3) Thanks [@mikenomitch](https://github.com/mikenomitch)! - Add support for custom tokens in `exposePort()` to enable stable preview URLs across deployments.
+
+  You can now pass a custom token when exposing ports to maintain consistent preview URLs between container restarts and deployments. This is useful for sharing URLs with users or maintaining stable references in production environments.
+
+  ```typescript
+  // With custom token - URL stays the same across restarts
+  const { url } = await sandbox.exposePort(8080, {
+    hostname: 'example.com',
+    token: 'my_token_v1' // 1-16 chars: a-z, 0-9, _
+  });
+  // url: https://8080-sandbox-id-my-token-v1.example.com
+
+  // Without token - generates random 16-char token (existing behavior)
+  const { url } = await sandbox.exposePort(8080, {
+    hostname: 'example.com'
+  });
+  // url: https://8080-sandbox-id-abc123random4567.example.com
+  ```
+
+  Custom tokens must be 1-16 characters containing only lowercase letters, numbers, and underscores.
+
+  **Breaking change:** Tokens can no longer contain hyphens. Existing preview URLs with hyphenated tokens (including some auto-generated ones) will stop working until the port is re-exposed.
+
+### Patch Changes
+
+- [#347](https://github.com/cloudflare/sandbox-sdk/pull/347) [`efdd0d7`](https://github.com/cloudflare/sandbox-sdk/commit/efdd0d779a8a225da5c26c5ac53011a37ab24315) Thanks [@roerohan](https://github.com/roerohan)! - Add Cloudflare AI Gateway support to OpenCode integration. Users can now route AI provider requests through Cloudflare AI Gateway for monitoring, caching, and rate limiting by adding a `cloudflareAIGateway` provider configuration with `accountId`, `gatewayId`, and optional `apiToken`.
+
+- [#342](https://github.com/cloudflare/sandbox-sdk/pull/342) [`7da85c0`](https://github.com/cloudflare/sandbox-sdk/commit/7da85c069543847633c32cedc0ef8329bf31478e) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Handle undefined environment variables as "unset" in setEnvVars
+
+  Environment variable APIs now properly handle undefined values:
+  - String values are exported as before
+  - undefined/null values now **unset** the variable (runs `unset VAR`)
+
+  This enables idiomatic JavaScript patterns:
+
+  ```typescript
+  await sandbox.setEnvVars({
+    API_KEY: 'new-key',
+    OLD_SECRET: undefined // unsets OLD_SECRET
+  });
+  ```
+
+  **Before**: `sandbox.setEnvVars({ KEY: undefined })` threw a runtime error
+  **After**: `sandbox.setEnvVars({ KEY: undefined })` runs `unset KEY`
+
+  TypeScript types now honestly accept `Record<string, string | undefined>`.
+
 ## 0.6.11
 
 ### Patch Changes
@@ -137,10 +188,10 @@
 
   ```dockerfile
   # Before
-  FROM cloudflare/sandbox:0.6.11
+  FROM cloudflare/sandbox:0.7.0
 
   # After
-  FROM cloudflare/sandbox:0.6.11-python
+  FROM cloudflare/sandbox:0.7.0-python
   ```
 
   Without this change, Python execution will fail with `PYTHON_NOT_AVAILABLE` error.

diff --git a/packages/sandbox/package.json b/packages/sandbox/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "0.6.11",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/sandbox-sdk"

diff --git a/packages/sandbox/src/version.ts b/packages/sandbox/src/version.ts
@@ -3,4 +3,4 @@
  * This file is auto-updated by .github/changeset-version.ts during releases
  * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
  */
-export const SDK_VERSION = '0.6.11';
+export const SDK_VERSION = '0.7.0';
diff --git a/tests/e2e/test-worker/Dockerfile b/tests/e2e/test-worker/Dockerfile
@@ -1,6 +1,6 @@
 # Base image Dockerfile (no Python)
 # Used for testing Python-not-available error handling
-FROM docker.io/cloudflare/sandbox-test:0.6.11
+FROM docker.io/cloudflare/sandbox-test:0.7.0
 
 # Expose ports used for testing
 # 8080: general testing

diff --git a/tests/e2e/test-worker/Dockerfile.opencode b/tests/e2e/test-worker/Dockerfile.opencode
@@ -1,6 +1,6 @@
 # E2E test Dockerfile for OpenCode
 # Uses the -opencode variant for testing the OpenCode integration
-FROM docker.io/cloudflare/sandbox-test:0.6.11-opencode
+FROM docker.io/cloudflare/sandbox-test:0.7.0-opencode
 
 # Expose ports used for testing
 # 4096: OpenCode server default port

diff --git a/tests/e2e/test-worker/Dockerfile.python b/tests/e2e/test-worker/Dockerfile.python
@@ -1,6 +1,6 @@
 # Integration test Dockerfile
 # Uses the -python variant because E2E tests include Python code execution tests
-FROM docker.io/cloudflare/sandbox-test:0.6.11-python
+FROM docker.io/cloudflare/sandbox-test:0.7.0-python
 
 # Expose ports used for testing
 # 8080: general testing

diff --git a/tests/e2e/test-worker/Dockerfile.standalone b/tests/e2e/test-worker/Dockerfile.standalone
@@ -1,7 +1,7 @@
 # Test the standalone binary pattern with an arbitrary base image
 # This validates that users can add sandbox capabilities to any Docker image
 
-ARG BASE_IMAGE=cloudflare/sandbox-test:0.6.11
+ARG BASE_IMAGE=cloudflare/sandbox-test:0.7.0
 FROM ${BASE_IMAGE} AS sandbox-source
 
 FROM node:20-slim
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		FROM docker.io/cloudflare/sandbox:0.6.11-python
		FROM docker.io/cloudflare/sandbox:0.7.0-python