Skip to main content
Treat a prepared image as a reproducible build output. Record its immutable UUID, base reference, dependency lock, setup revision, client version, and smoke-test result.

​
Refresh an environment

  1. Update the pinned base or dependency inputs.
  2. Re-run the documented OCI import, setup operation, or contree build workflow.
  3. Record the new result UUID.
  4. Run a disposable smoke test from that UUID.
  5. Move a development tag only after validation.
  6. Keep the previous known-good UUID for rollback until retention policy permits removal.
A tag can resolve to a different image later. Reproducible evaluation and recovery should use UUIDs.

​
Upgrade clients

The examples in this documentation target Python SDK 0.3.6 and CLI 0.9.4. Pin the exact line used in production, review the Sandboxes changelog and generated signatures, then run onboarding, state reuse, binary download, failure classification, and any streaming or subprocess checks used by the application. Python SDK 0.3.6 starts work when a prepared run object is awaited; it does not expose a public detached-start operation handle. A wait timeout attempts best-effort cancellation. REST transport behavior and CLI session behavior are separate contracts. Before upgrading, confirm that the Sandboxes service supports the intended backend, SDK, CLI, and MCP combination. Ask the Sandboxes team about deprecation timelines when an upgrade depends on a specific support window. Validate the exact versions against representative workload paths before moving production tags or clients. If a refreshed environment fails, switch workloads back to the recorded prior UUID, inspect the failed build or operation, and rebuild from pinned inputs. A rollback starts a new operation from saved filesystem state; it does not restore memory or processes.