Access, storage, and lifetime
These policies describe different parts of the workspace.
Check sandbox capabilities before offering private always-on creation. The API applies the project’s existing entitlement, capacity, and billing rules. The creator and billing owner remain separate identities.
Changing lifetime does not convert storage. Persistent files and user-installed tools under
/workspace survive runtime replacement. Running processes and system changes outside /workspace do not.
Deleting a sandbox removes its workspace files. Copy out files you need before deletion or expiry. This API does not provide a full VM or an SSH endpoint.
Readiness and activity
The lifecycle states are
pending, provisioning, running, error, and deleting.
Commands and files
Run short commands synchronously or stream their output as newline-delimited JSON. Use background commands for longer work. Background command IDs identify status, output, and cancellation requests. Command results contain separate stdout, stderr, and exit-code fields. File reads return UTF-8 content. Batch writes report an outcome for each requested path; HTTP 200 does not mean every file was written. Sandbox files are separate from project source and uploads in the Projects API. A deployment environment can supply a variable snapshot when the sandbox is created. Later configuration changes do not update that snapshot. The environment endpoint reports variable names with redacted values. A terminal session connects to the sandbox. Closing the terminal connection does not delete the sandbox. With[email protected], close() preserves persistent, always-on, and attached workspaces. It automatically deletes only a temporary workspace created by that client, after rechecking the current policy. Use delete() for deliberate deletion; the lazy client’s deleteOnClose: true option also explicitly requests deletion.
Older SDKs can delete the workspace when close() is called. REST lifetime and storage policies do not change an older SDK’s cleanup behavior. Check your installed version and use an API host serving the canonical /sandboxes contract.