Support undefined/null as unset in setEnvVars

[ghostwriternr]

Summary

setEnvVars({ KEY: undefined }) now runs unset KEY instead of throwing or silently doing nothing, enabling idiomatic patterns:

await sandbox.setEnvVars({
  API_KEY: 'new-key',      // exported
  OLD_SECRET: undefined,   // unset
});

[changeset-bot]

🦋 Changeset detected

Latest commit: 1a528ff

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@342

commit: 1a528ff

[github-actions]

🐳 Docker Images Published

Default:

FROM cloudflare/sandbox:0.0.0-pr-342-0abb711

With Python:

FROM cloudflare/sandbox:0.0.0-pr-342-0abb711-python

With OpenCode:

FROM cloudflare/sandbox:0.0.0-pr-342-0abb711-opencode

Version: 0.0.0-pr-342-0abb711

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:

COPY --from=cloudflare/sandbox:0.0.0-pr-342-0abb711 /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 20971037432 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-342-0abb711 cat /container-server/sandbox > sandbox && chmod +x sandbox

[github-actions]

OpenCode Review

The implementation looks well-architected and follows established codebase patterns effectively. The change enables idiomatic JavaScript patterns where undefined means "unset", which aligns with how optional fields work throughout the SDK.

Key strengths:

• Leverages existing shellEscape() and partitionEnvVars() utilities consistently across both layers
• Maintains atomic operations via session mutex locking
• POSIX environment variable name validation covers both set and unset operations
• Comprehensive test coverage including edge cases and E2E scenarios
• Type updates are consistent across the three-layer architecture

Documentation impact check: The changeset properly documents the behavior change for end users. No additional Cloudflare docs need updating since this doesn't change the core Workers/DO environment variable concepts.

Architecture consideration: The implementation correctly handles the flow through all three layers (SDK → DO → Container), with appropriate error handling and shell escaping at each boundary.

The approach is sound and ready to merge.