// Use when creating a changeset, preparing a release, or bumping versions. Covers which packages to reference, how to write user-facing changeset descriptions, the release automation flow, and the npm/Docker version sync requirement. (project)
Use when you need to exercise a real, running Sandbox deployment via HTTP — for example to validate SDK changes against a live container, reproduce a user-reported issue, or experiment with the API (including FUSE bucket mounts) without spinning up `wrangler dev`. Documents the Sandbox bridge worker reachable via `SANDBOX_WORKER_URL` + `SANDBOX_API_KEY` when the host injects them.
Use when navigating the codebase for the first time, adding a new client method, adding a new container handler/service, or understanding how a request flows from Worker through the Sandbox DO into the container. Covers the three-layer architecture, client pattern, container runtime structure, and monorepo layout. (project)
Use when writing or reviewing TypeScript in this repo. Covers the no-`any` rule and where to put new types, the uppercase-acronym style guide, and the rules for code comments (no historical context). (project)
Use when working in the examples/ directory, running an example with wrangler dev, adding a new example, or answering questions about EXPOSE directives and the local Docker dev loop. (project)
Use when adding logs, debugging, or working with the Logger across the SDK and container runtime. Covers the constructor-injection pattern, child loggers, env-var configuration, and test mocking. (project)
Use when working on or reviewing session execution, command handling, shell state, FIFO-based streaming, or stdout/stderr separation. Relevant for session.ts, command handlers, exec/execStream, or anything involving shell process management. (project)
| name | changesets |
| description | Use when creating a changeset, preparing a release, or bumping versions. Covers which packages to reference, how to write user-facing changeset descriptions, the release automation flow, and the npm/Docker version sync requirement. (project) |
This repository uses changesets to drive a fully automated release pipeline. Create a changeset whenever your change affects published packages.
A changeset should be created when there is a change that is observable to a consumer of the
@cloudflare/sandbox package. This includes:
Create a new file in .changeset/ (e.g. .changeset/your-feature-name.md):
---
'@cloudflare/sandbox': patch
---
Brief description of your change
Only reference @cloudflare/sandbox. Never list @repo/shared or @repo/sandbox-container — those are internal workspace packages and must not be versioned independently. Changes to them flow through the public package. Pre-commit hooks and CI enforce this.
Use patch for almost everything. The SDK is in beta:
patch — all normal changes (features, fixes, refactors)minor — breaking changes onlymajor — neverImportant: Changeset files should only reference @cloudflare/sandbox, never @repo/shared or @repo/sandbox-container. These internal packages should not be versioned independently - changes to them flow through the public package. Pre-commit hooks and CI will validate this rule.
Important: Write for end users. Changeset descriptions appear in GitHub releases - they're user-facing documentation, not internal notes.
# Bad - technical/internal focused
Add WebSocket transport for request multiplexing over a single connection
# Good - user-focused with clear benefit and usage
Add WebSocket transport to avoid sub-request limits in Workers and Durable Objects.
Enable with `useWebSocket: true` in sandbox options.
Releases run via .github/workflows/release.yml. There is no manual publishing step.
package.jsonDocker image version MUST match the npm package version. This is enforced via ARG SANDBOX_VERSION in packages/sandbox/Dockerfile. Don't try to release them out of band.
packages/sandbox/src/version.tslinux/amd64 only, matching Cloudflare's production runtime (ARM Macs use Rosetta/QEMU locally, preserving dev/prod parity)registry.cloudflare.com/library/sandbox:{version} (with -python, -opencode, -musl, -desktop variants). Any authenticated Cloudflare customer can pull from the library/ namespace without our account ID..changeset/ is descriptive (fix-stream-encoding.md, not patch.md)@cloudflare/sandbox is listedpatch (or minor for breaking changes)