code-sandboxes 1.4.6__tar.gz → 1.8.0__tar.gz

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/CHANGELOG.md

@@ -8,6 +8,48 @@
 
 ## Unreleased
 
+## 1.8.0
+
+- **The Datalayer builder** (`environments.adapters.datalayer`, PLAN_ENV.md
+  E1-07). The Dockerfile is generated from the lock — `uv pip sync
+  --require-hashes`, apt at the versions the lock recorded, `env` before
+  anything installs, `postInstall` as uid 1000 with no network — and the push
+  is by digest with an SBOM and provenance attestation, under the operability
+  tag `v<n>-<build_uid>` so a retried build cannot collide with the attempt
+  before it. `inspect`, `resolve`, `exists` and `delete` go through the ECR
+  API. Needs the `environments-builder` extra.
+- **The scan and the signature** (`environments.policy`,
+  `environments.attest`, E1-08, E1-09). A critical finding with a fixed
+  version blocks and one nothing fixes is recorded; the decision record keeps
+  the threshold it was decided under, so what stopped a build reads a month
+  later. cosign signs only once the scan passed, and a replay finds the
+  signature rather than pushing a second.
+- **A sandbox launches from an artifact** (E2-02): `Sandbox.create(artifact=…)`
+  hands each variant its own argument — an E2B template build, a Daytona
+  snapshot, a Modal image id through `Image.from_id`.
+- **Fixed, and a live defect:** Daytona's adapter took the image branch
+  whenever resources were requested, so a snapshot asked for with `cpu=` came
+  up from a plain Debian image running none of the snapshot's content, with
+  nothing saying so. The combination is refused (correction 13).
+
+## 1.7.0
+
+- **A version is resolved into one lock** (`code_sandboxes.environments.resolve`,
+  PLAN_ENV.md E1-04, D-9). Datalayer's protected constraints are merged over the
+  user's requirements — a requirement that agrees with a pin is dropped for it,
+  one that contradicts it is `DL_ENV_PROTECTED_PACKAGE` with the supported range
+  — the base is resolved to a digest per requested variant, and uv's refusals
+  are read into the error taxonomy: a conflict with the pair that cannot hold, a
+  package no index has, a protected pin, and `DL_ENV_PROVIDER_ERROR`, which is
+  retryable, for a failure that is not about the version.
+
+  The lock is uv's hashed output with the apt pins and the protected pins above
+  it as comments: one document that says everything a build installs, and still
+  a requirements file. `BuildkitResolveRunner` is D-9's solve, `FROM` the
+  resolved base digest; `LocalResolveRunner` runs `uv` where it is called, for
+  `plane local`, and refuses to pin apt rather than lock another
+  distribution's versions.
+
 - **Every variant has a real interrupt now, and can be reached to give it.**
   `Sandbox.interrupt` is two gates — `_executing_event` must be set, then
   `_do_interrupt` must answer — and seven variants failed one of them, each in

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/Makefile

@@ -32,10 +32,28 @@ build:
 test:
 	pytest -q
 
+## Build the datalayer-sandbox doctor as a single-file zipapp.
+doctor-zipapp:
+	python -m code_sandboxes.environments.doctor.build dist/datalayer-sandbox
+
+## Regenerate the Environment JSON Schema and the sandbox contract page.
+environments-generate:
+	python -m code_sandboxes.environments schema --write
+	python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+
+## Fail when the Environment JSON Schema or the sandbox contract page has drifted.
+environments-check:
+	python -m code_sandboxes.environments schema --check
+	python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+
 ## The Contents provider matrix against the real providers (skips those without credentials).
 live-matrix:
 	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_contents_live_matrix.py
 
+## Lose a sandbox on each live provider and check the harness says so.
+kill-relaunch:
+	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_the_kill_relaunch_drill.py
+
 clean: ## clean
 	git clean -fdx
 

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.4.6
+Version: 1.8.0
 Project-URL: Home, https://github.com/datalayer/code-sandboxes
 Author-email: Datalayer <info@datalayer.io>
 License: BSD 3-Clause License
@@ -73,6 +73,8 @@ Provides-Extra: docker
 Requires-Dist: docker>=6.0; extra == 'docker'
 Provides-Extra: e2b
 Requires-Dist: e2b-code-interpreter>=2.9.1; extra == 'e2b'
+Provides-Extra: environments-builder
+Requires-Dist: boto3>=1.34; extra == 'environments-builder'
 Provides-Extra: google-colab
 Provides-Extra: kaggle
 Requires-Dist: kaggle>=1.6; extra == 'kaggle'

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.4.6"
+__version__ = "1.8.0"

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/code_sandboxes/base.py

@@ -499,6 +499,7 @@ class Sandbox(ABC):
         timeout: float | None = None,
         name: str | None = None,
         environment: str | None = None,
+        environment_version: str | int | None = None,
         gpu: str | None = None,
         cpu: float | None = None,
         memory: int | None = None,
@@ -507,6 +508,7 @@ class Sandbox(ABC):
         allowed_hosts: list[str] | None = None,
         tags: dict[str, str] | None = None,
         examples: list[tuple[str, str]] | None = None,
+        artifact: Any = None,
         **kwargs,
     ) -> Sandbox:
         """Factory method to create a sandbox of the specified variant.
@@ -525,7 +527,12 @@ class Sandbox(ABC):
             config: Optional full configuration object (overrides individual params).
             timeout: Default timeout for code execution in seconds.
             name: Optional name for the sandbox.
-            environment: Runtime environment (e.g., "ai-agents-env").
+            environment: Runtime environment (e.g., "ai-agents-env"), or a user
+                environment as "<account-handle>/<name>" or by its uid.
+            environment_version: Which version of a user environment to launch:
+                its number, or a version uid. Without one the promoted version
+                launches, which is what a platform environment always does.
+                Only the datalayer variant has versions (PLAN_ENV.md, E1-19).
             gpu: GPU type to use (e.g., "T4", "A100", "H100"). Only for datalayer.
             cpu: CPU cores to allocate.
             memory: Memory limit in MB.
@@ -559,6 +566,7 @@ class Sandbox(ABC):
             config = SandboxConfig(
                 timeout=timeout or 30.0,
                 environment=environment or DEFAULT_ENVIRONMENT,
+                environment_version=environment_version,
                 memory_limit=memory * 1024 * 1024 if memory else None,
                 cpu_limit=cpu,
                 env_vars=env or {},
@@ -582,6 +590,17 @@ class Sandbox(ABC):
 
         variant_value = normalize_variant(variant)
 
+        if artifact is not None:
+            # One neutral reference, translated into the argument its variant
+            # takes: a template build for E2B, a snapshot for Daytona, an
+            # image id for Modal (PLAN_ENV.md E2-02). A caller holding an
+            # Environment's artifact should not have to know which. What the
+            # caller passed itself wins, so naming both is not a surprise.
+            from .environments.builders import launch_arguments
+
+            for name_, value in launch_arguments(artifact).items():
+                kwargs.setdefault(name_, value)
+
         if variant_value == "eval":
             sandbox = EvalSandbox(config=config, **kwargs)
         elif variant_value == "docker":

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/code_sandboxes/datalayer_sandbox.py

@@ -475,11 +475,19 @@ class DatalayerSandbox(Sandbox):
             # Build sandbox name
             sandbox_name = self.config.name or f"sandbox-{self._sandbox_id[:8]}"
 
+            # Which VERSION of that environment, passed through as the
+            # environment is (PLAN_ENV.md, E1-19). `None` means the promoted
+            # version, which is what every platform environment launches — and
+            # what every sandbox launched before there were versions asked for.
+            # The GPU rewrite above is left exactly as it is until E4-11 (D-20).
+            environment_version = self.config.environment_version
+
             # Create the runtime (optionally from snapshot)
             if self._snapshot_name:
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                     snapshot_name=self._snapshot_name,
                 )
@@ -487,6 +495,7 @@ class DatalayerSandbox(Sandbox):
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                 )
 

{code_sandboxes-1.4.6 → code_sandboxes-1.8.0}/code_sandboxes/daytona_sandbox.py

@@ -510,8 +510,13 @@ class DaytonaSandbox(Sandbox):
         given = {key: value for key, value in settings.items() if value}
         return daytona.DaytonaConfig(**given) if given else None
 
-    def _create_params(self, daytona: Any) -> Any:
-        """What to ask Daytona for, from the configuration of this sandbox."""
+    def _create_params(self, daytona: Any) -> Any:  # noqa: C901
+        """What to ask Daytona for, from the configuration of this sandbox.
+
+        Read top to bottom: what it refuses — a snapshot with resources, a
+        snapshot with an image — is the rule, and splitting the refusals
+        across helpers would hide them from the one place a reader looks.
+        """
         common: dict[str, Any] = {"labels": self._labels()}
         if self.config.env_vars:
             common["env_vars"] = dict(self.config.env_vars)
@@ -538,6 +543,27 @@ class DaytonaSandbox(Sandbox):
             common["auto_delete_interval"] = 0
         if self._spot:
             common.update(self._spot_params(resources))
+        if self._snapshot is not None:
+            # A snapshot carries the machine it was created for — Daytona bakes
+            # CPU, memory, disk and GPU into it, and it is region-scoped — so
+            # asking for resources beside one asks for two different machines.
+            # This used to take the image branch instead: the sandbox came up
+            # from a Debian image with the resources asked for, running none of
+            # the content the snapshot held, and nothing said so (PLAN_ENV.md
+            # correction 13, E2-02). A resource change is a new snapshot.
+            if resources is not None:
+                raise SandboxConfigurationError(
+                    "A Daytona snapshot carries its own CPU, memory, disk and GPU, so "
+                    "cpu=, memory= and gpu= cannot be passed with snapshot=: the sandbox "
+                    "would have come up from a plain image instead, with none of the "
+                    "snapshot's content. Create a snapshot for the machine you want, or "
+                    "pass image= with the resources."
+                )
+            if self._image is not None:
+                raise SandboxConfigurationError(
+                    "snapshot= and image= are two different things to start from; pass one. "
+                    "A snapshot is what an Environment build records for this variant."
+                )
         if self._image is not None or resources is not None:
             image = self._image
             if image is None:
@@ -547,6 +573,8 @@ class DaytonaSandbox(Sandbox):
                     else daytona.Image.debian_slim()
                 )
             return daytona.CreateSandboxFromImageParams(image=image, resources=resources, **common)
+        # No snapshot named and nothing asked for: Daytona's own default, which
+        # is what `snapshot=None` means to it.
         return daytona.CreateSandboxFromSnapshotParams(snapshot=self._snapshot, **common)
 
     def _spot_params(self, resources: Any | None) -> dict[str, Any]:

code_sandboxes-1.8.0/code_sandboxes/environments/__init__.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Environments: define once, resolve once, build an immutable artifact per variant.
+
+An **Environment** is the stable object a person names. An **Environment
+Version** is immutable once it leaves draft: its spec, the lock resolved from
+it, and its build outcome. An **Environment Artifact** is the build output of
+one version on one variant — an OCI digest for Datalayer, a build id for E2B,
+a snapshot id for Daytona, an image id for Modal.
+
+This package holds what every party to that life shares, and nothing
+provider-specific:
+
+- :mod:`.spec` — the canonical specification and its rules;
+- :mod:`.resolve` — the lock a version is resolved into, once (D-9);
+- :mod:`.policy` — whether an artifact's scan lets it be used (D-11);
+- :mod:`.attest` — the scan and the signature it needs before anything runs it;
+- :mod:`.contract` — ``sandbox-contract/v1`` and the Dockerfile validator;
+- :mod:`.lifecycle` — the version states and their legal moves;
+- :mod:`.errors` — the error taxonomy every provider error maps into;
+- :mod:`.builders` — the builder interface and its neutral types;
+- :mod:`.conformance` — the checks an artifact passes before it is ready;
+- :mod:`.redact` — a build's log with its secrets taken out before it is stored;
+- :mod:`.doctor` — the in-sandbox contract checker.
+
+The builders themselves are in :mod:`.adapters`, loaded by variant.
+"""
+
+from __future__ import annotations
+
+from .attest import Attestor, attest_artifact, signature_tag
+from .bases import APPROVED_BASES, ApprovedBase
+from .builders import (
+    ArtifactReference,
+    BuildRequest,
+    CapabilityReport,
+    CapabilitySet,
+    CheckResult,
+    EnvironmentBuilder,
+    ValidationResult,
+    get_builder,
+)
+from .canonical import canonical_digest, canonical_json
+from .contract import (
+    CONTRACT_V1,
+    SANDBOX_CONTRACT_V1,
+    SUPPORTED_CONTRACTS,
+    SandboxContract,
+    check_dockerfile,
+    validate_dockerfile,
+)
+from .errors import ERROR_CODES, EnvironmentsError, ErrorCode, map_provider_error
+from .lifecycle import VersionState, build_outcome, can_transition, transition
+from .policy import DEFAULT_POLICY, PolicyDecision, ScanPolicy, decide, refuse_if_blocked
+from .resolve import (
+    LOCK_FORMAT,
+    BuildkitResolveRunner,
+    LocalResolveRunner,
+    ResolveRunner,
+    locked_versions,
+    merge_requirements,
+    parse_resolver_failure,
+    protected_pins,
+    resolve_environment,
+)
+from .spec import (
+    API_VERSION,
+    VARIANTS,
+    Environment,
+    EnvironmentSpec,
+    parse_environment,
+    spec_digest,
+    spec_findings,
+    validate_environment,
+)
+
+__all__ = [
+    "API_VERSION",
+    "APPROVED_BASES",
+    "CONTRACT_V1",
+    "DEFAULT_POLICY",
+    "ERROR_CODES",
+    "LOCK_FORMAT",
+    "SANDBOX_CONTRACT_V1",
+    "SUPPORTED_CONTRACTS",
+    "VARIANTS",
+    "ApprovedBase",
+    "ArtifactReference",
+    "Attestor",
+    "BuildRequest",
+    "BuildkitResolveRunner",
+    "CapabilityReport",
+    "CapabilitySet",
+    "CheckResult",
+    "Environment",
+    "EnvironmentBuilder",
+    "EnvironmentSpec",
+    "EnvironmentsError",
+    "ErrorCode",
+    "LocalResolveRunner",
+    "PolicyDecision",
+    "ResolveRunner",
+    "SandboxContract",
+    "ScanPolicy",
+    "ValidationResult",
+    "VersionState",
+    "attest_artifact",
+    "build_outcome",
+    "can_transition",
+    "canonical_digest",
+    "canonical_json",
+    "check_dockerfile",
+    "decide",
+    "get_builder",
+    "locked_versions",
+    "map_provider_error",
+    "merge_requirements",
+    "parse_environment",
+    "parse_resolver_failure",
+    "protected_pins",
+    "refuse_if_blocked",
+    "resolve_environment",
+    "signature_tag",
+    "spec_digest",
+    "spec_findings",
+    "transition",
+    "validate_dockerfile",
+    "validate_environment",
+]

code_sandboxes-1.8.0/code_sandboxes/environments/__main__.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Generate what is generated from the Environment models.
+
+python -m code_sandboxes.environments schema --write [PATH]
+python -m code_sandboxes.environments schema --check [PATH]
+python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import contract, schema
+
+_COMMANDS = {"schema": schema.main, "contract": contract.main}
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] not in _COMMANDS:
+        print(__doc__.strip(), file=sys.stderr)  # noqa: T201 - a command's own output
+        return 2
+    return _COMMANDS[arguments[0]](arguments[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_sandboxes-1.8.0/code_sandboxes/environments/adapters/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""The provider-specific Environment builders, one module per variant.
+
+Not neutral: each module speaks its provider's SDK. They are loaded only by
+:func:`code_sandboxes.environments.builders.get_builder`, and only where the
+build runs — the durable worker — never by a service that merely describes
+or launches an Environment.
+"""