Sandbox Sdk

Cloudflare Sandbox SDK

Use current Cloudflare docs and the installed package as the API contract. The SDK and its container topology evolve quickly; inspect package exports, types, Wrangler schema, and generated configuration before coding.

Establish the isolation contract

Identify:

• who chooses the sandbox ID and how it is scoped to a tenant or session;
• which code, files, environment variables, and network access are untrusted;
• what must survive container sleep or recreation;
• which operations need a shared session versus isolated execution; and
• whether an exposed service is private, temporary, or public.

A Sandbox is backed by a Durable Object and its container starts lazily. The same ID selects the same logical Sandbox, but container-local files, processes, and shell state can be lost after sleep or restart. Put durable application state outside the ephemeral container filesystem.

Configure from current docs

Verify the exact container, Durable Object binding, and class lifecycle required by the installed SDK. Re-export the SDK's Sandbox class from the Worker when the current integration requires it. Do not copy a pinned image tag, lifecycle declaration, instance type, or preview-domain configuration from this skill.

Use api-quick-ref.md only after checking installed types. Use examples.md to locate a relevant upstream example rather than combining several patterns speculatively.

Choose execution deliberately

• Use command/process APIs when exit status, streams, or process lifecycle is the contract.
• Use code-interpreter APIs when structured rich results or a deliberate session is required.
• Disable or avoid shared default sessions when calls must be isolated.
• Scope IDs and credentials so one tenant cannot address another tenant's sandbox.
• Bound input, runtime, output, files, processes, and cleanup according to the untrusted-code threat model.
• Treat preview URLs as public capabilities unless an owning authentication layer proves otherwise. Check current custom-domain and tunnel requirements.

Verify the real lifecycle

Test the exact package version and generated Worker bundle. Exercise creation, one representative command or code run, expected file/session behavior, sleep/recreation when persistence matters, cleanup, and any exposed route. Successful object creation alone does not prove container execution or preview routing.