modAL 1.5.3.dev9__tar.gz → 1.5.3.dev11__tar.gz

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.3.dev9
+Version: 1.5.3.dev11
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/_function_variants.py

@@ -171,7 +171,7 @@ class _FunctionOptions:
             replace_secret_ids=bool(self.secrets),
             replace_volume_mounts=len(volume_mounts) > 0,
             volume_mounts=volume_mounts,
-            cloud_bucket_mounts=cloud_bucket_mounts_to_proto(self.cloud_bucket_mounts),
+            cloud_bucket_mounts=cloud_bucket_mounts_to_proto(self.cloud_bucket_mounts)[0],
             replace_cloud_bucket_mounts=bool(self.cloud_bucket_mounts),
             resources=self.resources,
             retry_policy=self.retry_policy,

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/_functions.py

@@ -1000,7 +1000,7 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
                     untrusted=restrict_modal_access,
                     single_use_containers=single_use_containers,
                     max_inputs=int(single_use_containers),  # TODO(michael) remove after worker rollover
-                    cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts),
+                    cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts)[0],
                     scheduler_placement=scheduler_placement,
                     is_class=info.is_service_class(),
                     class_parameter_info=info.class_parameter_info(),

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/_utils/task_command_router_client.py

@@ -974,3 +974,8 @@ class TaskCommandRouterClient:
         return await self._unary_call_with_deadline(
             self._stub.TaskSnapshotFilesystem, request, timeout=timeout, **kwargs
         )
+
+    async def snapshot_memory(
+        self, request: sr_pb2.TaskSnapshotMemoryRequest, *, timeout: float, **kwargs
+    ) -> sr_pb2.TaskSnapshotMemoryResponse:
+        return await self._unary_call_with_deadline(self._stub.TaskSnapshotMemory, request, timeout=timeout, **kwargs)

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/client.pyi

@@ -37,7 +37,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.5.3.dev9",
+        version: str = "1.5.3.dev11",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -207,7 +207,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.5.3.dev9",
+        version: str = "1.5.3.dev11",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/cloud_bucket_mount.py

@@ -121,11 +121,14 @@ class _CloudBucketMount:
     force_path_style: bool = False
 
 
-def cloud_bucket_mounts_to_proto(mounts: Sequence[tuple[str, _CloudBucketMount]]) -> list[api_pb2.CloudBucketMount]:
+def cloud_bucket_mounts_to_proto(
+    mounts: Sequence[tuple[str, _CloudBucketMount]], split_ephemeral_credentials: bool = False
+) -> tuple[list[api_pb2.CloudBucketMount], dict[str, api_pb2.StringMap]]:
     """mdmd:hidden
     Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server.
     """
     cloud_bucket_mounts: list[api_pb2.CloudBucketMount] = []
+    cloud_bucket_credentials: dict[str, api_pb2.StringMap] = {}
 
     for path, mount in mounts:
         # crude mapping from mount arguments to type.
@@ -153,11 +156,20 @@ def cloud_bucket_mounts_to_proto(mounts: Sequence[tuple[str, _CloudBucketMount]]
         else:
             key_prefix = mount.key_prefix
 
+        credentials_secret_id = ""
+        if secret := mount.secret:
+            if split_ephemeral_credentials and secret._load_env_dict:
+                env_dict = secret._load_env_dict()
+                credientials = api_pb2.StringMap(contents=env_dict)
+                cloud_bucket_credentials[path] = credientials
+            else:
+                credentials_secret_id = secret.object_id
+
         cloud_bucket_mount = api_pb2.CloudBucketMount(
             bucket_name=mount.bucket_name,
             bucket_endpoint_url=mount.bucket_endpoint_url,
             mount_path=path,
-            credentials_secret_id=mount.secret.object_id if mount.secret else "",
+            credentials_secret_id=credentials_secret_id,
             read_only=mount.read_only,
             bucket_type=bucket_type,
             requester_pays=mount.requester_pays,
@@ -167,7 +179,7 @@ def cloud_bucket_mounts_to_proto(mounts: Sequence[tuple[str, _CloudBucketMount]]
         )
         cloud_bucket_mounts.append(cloud_bucket_mount)
 
-    return cloud_bucket_mounts
+    return cloud_bucket_mounts, cloud_bucket_credentials
 
 
 CloudBucketMount = synchronize_api(_CloudBucketMount)

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/cloud_bucket_mount.pyi

@@ -126,8 +126,8 @@ class _CloudBucketMount:
         ...
 
 def cloud_bucket_mounts_to_proto(
-    mounts: collections.abc.Sequence[tuple[str, _CloudBucketMount]],
-) -> list[modal_proto.api_pb2.CloudBucketMount]:
+    mounts: collections.abc.Sequence[tuple[str, _CloudBucketMount]], split_ephemeral_credentials: bool = False
+) -> tuple[list[modal_proto.api_pb2.CloudBucketMount], dict[str, modal_proto.api_pb2.StringMap]]:
     """mdmd:hidden
     Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server.
     """

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/exception.py

@@ -188,6 +188,10 @@ class SandboxTimeoutError(TimeoutError):
     """Raised when a Sandbox exceeds its execution duration limit and times out."""
 
 
+class SnapshotCreationError(Error):
+    """Raised when a Sandbox fails to create an exit snapshot."""
+
+
 class ExecTimeoutError(TimeoutError):
     """Raised when a container process exceeds its execution duration limit and times out."""
 

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/sandbox.py

@@ -52,10 +52,13 @@ from .exception import (
     ClientClosed,
     ConflictError,
     ExecutionError,
+    InternalError,
     InvalidError,
     NotFoundError,
     SandboxTerminatedError,
     SandboxTimeoutError,
+    SnapshotCreationError,
+    TimeoutError,
 )
 from .file_io import _FileIO, ls, mkdir, rm, watch
 from .io_streams import (
@@ -77,6 +80,8 @@ from .stream_type import StreamType
 from .types import FileWatchEvent, FileWatchEventType, SandboxConnectCredentials
 
 _default_image: _Image = _Image.debian_slim()
+_EXIT_SNAPSHOT_POLL_INTERVAL_SECONDS = 1.0
+_EXIT_SNAPSHOT_NOT_FOUND_ERROR_CODES = frozenset((api_pb2.SandboxGetExitSnapshotResponse.ERROR_CODE_TIMEOUT,))
 
 
 async def _gather_load_with_timings(
@@ -472,7 +477,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 nfs_mounts=network_file_system_mount_protos(validated_network_file_systems),
                 runtime=config.get("function_runtime"),
                 runtime_debug=config.get("function_runtime_debug"),
-                cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts),
+                cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts)[0],
                 volume_mounts=volume_mounts,
                 pty_info=pty_info,
                 scheduler_placement=scheduler_placement,
@@ -845,6 +850,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         verbose: bool = False,
         custom_domain: str | None = None,
         client: _Client | None = None,
+        _experimental_enable_snapshot: bool = False,
     ) -> "_Sandbox":
         """Create a sandbox using the V2 backend.
 
@@ -860,8 +866,9 @@ class _Sandbox(_Object, type_prefix="sb"):
         tuple that additionally sets a hard limit (fractional CPU cores; memory
         in MiB), matching `Sandbox.create()`.
 
-        Features like memory snapshots, network file systems, and GPUs are not
-        supported.
+        Pass `_experimental_enable_snapshot=True` to create a sandbox that can be
+        snapshotted with `._experimental_snapshot()`. Features like network
+        file systems and GPUs are not supported.
 
         Set `i6pn=True` to enable private IPv6 networking so sandboxes in the same
         workspace can address each other directly at their `i6pn.modal.local`
@@ -961,8 +968,9 @@ class _Sandbox(_Object, type_prefix="sb"):
             for _, vol in validated_volumes:
                 dep_tasks.append(resolver.load(vol, load_context))
             for _, cloud_bucket_mount in cloud_bucket_mounts:
-                if cloud_bucket_mount.secret:
-                    dep_tasks.append(resolver.load(cloud_bucket_mount.secret, load_context))
+                if secret := cloud_bucket_mount.secret:
+                    if not secret._is_ephemeral:
+                        dep_tasks.append(resolver.load(cloud_bucket_mount.secret, load_context))
             if proxy:
                 dep_tasks.append(resolver.load(proxy, load_context))
             dep_timings = await _gather_load_with_timings(dep_tasks) if dep_tasks else []
@@ -971,6 +979,10 @@ class _Sandbox(_Object, type_prefix="sb"):
 
             volume_mounts = [_volume_to_mount_proto(path, volume) for path, volume in validated_volumes]
 
+            cloud_bucket_mount_protos, cloud_bucket_credientials = cloud_bucket_mounts_to_proto(
+                cloud_bucket_mounts, split_ephemeral_credentials=True
+            )
+
             definition = api_pb2.Sandbox(
                 entrypoint_args=args,
                 image_id=image.object_id,
@@ -995,12 +1007,13 @@ class _Sandbox(_Object, type_prefix="sb"):
                 inbound_cidr_allowlist=list(inbound_cidr_allowlist) if inbound_cidr_allowlist is not None else [],
                 i6pn_enabled=i6pn,
                 volume_mounts=volume_mounts,
-                cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts),
+                cloud_bucket_mounts=cloud_bucket_mount_protos,
                 readiness_probe=(readiness_probe._to_proto() if readiness_probe else None),
                 experimental_options_v2=(
                     {k: str(v) for k, v in experimental_options.items()} if experimental_options else None
                 ),
                 custom_domain=custom_domain,
+                enable_snapshot=_experimental_enable_snapshot,
             )
 
             tag_protos = [api_pb2.SandboxTag(tag_name=k, tag_value=v) for k, v in tags.items()] if tags else []
@@ -1009,6 +1022,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 definition=definition,
                 ephemeral_secrets=api_pb2.StringMap(contents=env_dict) if env_dict else None,
                 tags=tag_protos,
+                cloud_bucket_mount_credentials=cloud_bucket_credientials,
             )
             assert load_context.client._auth_token_manager
             auth_token = await load_context.client._auth_token_manager.get_token()
@@ -1401,6 +1415,68 @@ class _Sandbox(_Object, type_prefix="sb"):
         req = sr_pb2.TaskSetNetworkAccessRequest(task_id=task_id, network_access=network_access)
         await command_router_client.set_network_access(req)
 
+    async def _experimental_get_exit_snapshot(self, timeout: float | None = 60) -> _Image:
+        """Get the exit filesystem snapshot image.
+
+        Args:
+            timeout: Client-side deadline in seconds (default 60). Use `None` to
+                poll until the snapshot reaches a terminal state. Use `0` to
+                perform an immediate check.
+
+        Returns:
+            The exit snapshot Image.
+
+        Raises:
+            InvalidError: If `timeout` is negative, or if exit snapshot is not
+                enabled for the sandbox.
+            TimeoutError: If `timeout` elapses before the snapshot reaches a
+                terminal state. This includes `timeout=0` when the snapshot is
+                still pending.
+            SnapshotCreationError: If no exit snapshot image will be produced.
+            NotFoundError: If the sandbox does not exist.
+            PermissionDeniedError: If the caller cannot access the sandbox.
+            InternalError: If persisted snapshot state is malformed.
+            ServiceError: If a transient client/server communication failure occurs.
+        """
+        if timeout is not None and timeout < 0:
+            raise InvalidError("timeout must be non-negative or None")
+
+        deadline = None if timeout is None else time.monotonic() + timeout
+        timeout_message = f"timed out waiting for exit snapshot for Sandbox {self.object_id}"
+
+        while True:
+            resp: api_pb2.SandboxGetExitSnapshotResponse = await self._client.stub.SandboxGetExitSnapshot(
+                api_pb2.SandboxGetExitSnapshotRequest(sandbox_id=self.object_id)
+            )
+            outcome = resp.WhichOneof("outcome")
+
+            if outcome == "success":
+                if not resp.success.image_id:
+                    raise InternalError("Exit snapshot result is missing image ID")
+                return _Image._new_hydrated(resp.success.image_id, self._client, None)
+
+            if outcome == "error":
+                if resp.error.error_code in _EXIT_SNAPSHOT_NOT_FOUND_ERROR_CODES:
+                    message = resp.error.message or "No exit snapshot image will be produced"
+                    raise SnapshotCreationError(message)
+                message = resp.error.message or "Exit snapshot state is malformed"
+                raise InternalError(message)
+
+            if outcome != "pending":
+                raise InternalError("Exit snapshot response is missing an outcome")
+
+            sleep_for = _EXIT_SNAPSHOT_POLL_INTERVAL_SECONDS
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError(timeout_message)
+                sleep_for = min(sleep_for, remaining)
+
+            await asyncio.sleep(sleep_for)
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise TimeoutError(timeout_message)
+
     async def snapshot_filesystem(
         self,
         timeout: int = 55,
@@ -2079,19 +2155,27 @@ class _Sandbox(_Object, type_prefix="sb"):
         )
 
     async def _experimental_snapshot(self) -> _SandboxSnapshot:
-        self._ensure_v1("_experimental_snapshot")
-        await self._get_task_id()
-        snap_req = api_pb2.SandboxSnapshotRequest(sandbox_id=self.object_id)
-        snap_resp = await self._client.stub.SandboxSnapshot(snap_req)
+        if self._is_v2:
+            task_id = await self._get_task_id()
+            command_router_client = await self._get_command_router_client(task_id)
+            snap_v2_resp = await command_router_client.snapshot_memory(
+                sr_pb2.TaskSnapshotMemoryRequest(task_id=task_id, idempotency_key=str(uuid.uuid4())),
+                timeout=55.0,
+            )
+            snapshot_id = snap_v2_resp.snapshot_id
+        else:
+            await self._get_task_id()
+            snap_req = api_pb2.SandboxSnapshotRequest(sandbox_id=self.object_id)
+            snap_resp = await self._client.stub.SandboxSnapshot(snap_req)
 
-        snapshot_id = snap_resp.snapshot_id
+            snapshot_id = snap_resp.snapshot_id
 
-        # wait for the snapshot to succeed. this is implemented as a second idempotent rpc
-        # because the snapshot itself may take a while to complete.
-        wait_req = api_pb2.SandboxSnapshotWaitRequest(snapshot_id=snapshot_id, timeout=55.0)
-        wait_resp = await self._client.stub.SandboxSnapshotWait(wait_req)
-        if wait_resp.result.status != api_pb2.GenericResult.GENERIC_STATUS_SUCCESS:
-            raise ExecutionError(wait_resp.result.exception)
+            # wait for the snapshot to succeed. this is implemented as a second idempotent rpc
+            # because the snapshot itself may take a while to complete.
+            wait_req = api_pb2.SandboxSnapshotWaitRequest(snapshot_id=snapshot_id, timeout=55.0)
+            wait_resp = await self._client.stub.SandboxSnapshotWait(wait_req)
+            if wait_resp.result.status != api_pb2.GenericResult.GENERIC_STATUS_SUCCESS:
+                raise ExecutionError(wait_resp.result.exception)
 
         async def _load(
             self: _SandboxSnapshot, resolver: Resolver, load_context: LoadContext, existing_object_id: str | None
@@ -2102,7 +2186,8 @@ class _Sandbox(_Object, type_prefix="sb"):
         rep = "SandboxSnapshot()"
         # TODO: use ._new_hydrated instead
         obj = _SandboxSnapshot._from_loader(_load, rep, hydrate_lazily=True, load_context_overrides=LoadContext.empty())
-        obj._hydrate(snapshot_id, self._client, None)
+        metadata = api_pb2.SandboxSnapshotHandleMetadata(is_v2=self._is_v2)
+        obj._hydrate(snapshot_id, self._client, metadata)
 
         return obj
 
@@ -2113,27 +2198,41 @@ class _Sandbox(_Object, type_prefix="sb"):
         *,
         name: str | None = _DEFAULT_SANDBOX_NAME_OVERRIDE,
     ):
+        """Restore a Sandbox from a memory snapshot.
+
+        The restore targets the same backend the snapshot was taken from. A V1
+        snapshot restores as a V1 sandbox, a V2 snapshot as a V2 sandbox.
+        """
         client = client or await _Client.from_env()
 
+        if snapshot._is_v2 is None:
+            await snapshot.hydrate(client=client)
+        use_v2 = bool(snapshot._is_v2)
+
         if name is not None and name != _DEFAULT_SANDBOX_NAME_OVERRIDE:
             check_object_name(name, "Sandbox")
 
         if name is _DEFAULT_SANDBOX_NAME_OVERRIDE:
-            restore_req = api_pb2.SandboxRestoreRequest(
-                snapshot_id=snapshot.object_id,
-                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_UNSPECIFIED,
-            )
+            override_type = api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_UNSPECIFIED
+            name_override = None
         elif name is None:
-            restore_req = api_pb2.SandboxRestoreRequest(
-                snapshot_id=snapshot.object_id,
-                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_NONE,
-            )
+            override_type = api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_NONE
+            name_override = None
         else:
-            restore_req = api_pb2.SandboxRestoreRequest(
-                snapshot_id=snapshot.object_id,
-                sandbox_name_override=name,
-                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_STRING,
+            override_type = api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_STRING
+            name_override = name
+
+        if use_v2:
+            return await _Sandbox._experimental_from_snapshot_v2(
+                snapshot, client, override_type=override_type, name_override=name_override
             )
+
+        restore_req = api_pb2.SandboxRestoreRequest(
+            snapshot_id=snapshot.object_id,
+            sandbox_name_override_type=override_type,
+        )
+        if name_override is not None:
+            restore_req.sandbox_name_override = name_override
         # Pin the restored Sandbox to a specific worker when MODAL_WORKER_ID is
         # set.
         if worker_id := config.get("worker_id"):
@@ -2153,6 +2252,33 @@ class _Sandbox(_Object, type_prefix="sb"):
             raise ExecutionError(resp.task_result.exception)
         return sandbox
 
+    @staticmethod
+    async def _experimental_from_snapshot_v2(
+        snapshot: _SandboxSnapshot,
+        client: _Client,
+        *,
+        override_type: "api_pb2.SandboxRestoreRequest.SandboxNameOverrideType.ValueType",
+        name_override: str | None,
+    ) -> "_Sandbox":
+        restore_req = api_pb2.SandboxRestoreV2Request(
+            snapshot_id=snapshot.object_id,
+            sandbox_name_override_type=override_type,
+        )
+        if name_override is not None:
+            restore_req.sandbox_name_override = name_override
+        if worker_id := config.get("worker_id"):
+            restore_req.worker_id = worker_id
+
+        assert client._auth_token_manager
+        auth_token = await client._auth_token_manager.get_token()
+        restore_resp: api_pb2.SandboxRestoreV2Response = await client.stub.SandboxRestoreV2(
+            restore_req, metadata=[("x-modal-auth-token", auth_token)]
+        )
+
+        sandbox = await _Sandbox.from_id(restore_resp.sandbox_id, client)
+        sandbox._task_id = restore_resp.task_id
+        return sandbox
+
     @property
     def filesystem(self) -> _SandboxFilesystem:
         """Namespace for Sandbox filesystem APIs."""

{modal-1.5.3.dev9 → modal-1.5.3.dev11}/modal/sandbox.pyi

@@ -393,6 +393,7 @@ class _Sandbox(modal._object._Object):
         verbose: bool = False,
         custom_domain: typing.Optional[str] = None,
         client: typing.Optional[modal.client._Client] = None,
+        _experimental_enable_snapshot: bool = False,
     ) -> _Sandbox:
         """Create a sandbox using the V2 backend.
 
@@ -408,8 +409,9 @@ class _Sandbox(modal._object._Object):
         tuple that additionally sets a hard limit (fractional CPU cores; memory
         in MiB), matching `Sandbox.create()`.
 
-        Features like memory snapshots, network file systems, and GPUs are not
-        supported.
+        Pass `_experimental_enable_snapshot=True` to create a sandbox that can be
+        snapshotted with `._experimental_snapshot()`. Features like network
+        file systems and GPUs are not supported.
 
         Set `i6pn=True` to enable private IPv6 networking so sandboxes in the same
         workspace can address each other directly at their `i6pn.modal.local`
@@ -571,6 +573,31 @@ class _Sandbox(modal._object._Object):
         """
         ...
 
+    async def _experimental_get_exit_snapshot(self, timeout: typing.Optional[float] = 60) -> modal._image._Image:
+        """Get the exit filesystem snapshot image.
+
+        Args:
+            timeout: Client-side deadline in seconds (default 60). Use `None` to
+                poll until the snapshot reaches a terminal state. Use `0` to
+                perform an immediate check.
+
+        Returns:
+            The exit snapshot Image.
+
+        Raises:
+            InvalidError: If `timeout` is negative, or if exit snapshot is not
+                enabled for the sandbox.
+            TimeoutError: If `timeout` elapses before the snapshot reaches a
+                terminal state. This includes `timeout=0` when the snapshot is
+                still pending.
+            SnapshotCreationError: If no exit snapshot image will be produced.
+            NotFoundError: If the sandbox does not exist.
+            PermissionDeniedError: If the caller cannot access the sandbox.
+            InternalError: If persisted snapshot state is malformed.
+            ServiceError: If a transient client/server communication failure occurs.
+        """
+        ...
+
     async def snapshot_filesystem(
         self, timeout: int = 55, *, ttl: typing.Optional[int] = 2592000
     ) -> modal._image._Image:
@@ -852,7 +879,22 @@ class _Sandbox(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         *,
         name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
-    ): ...
+    ):
+        """Restore a Sandbox from a memory snapshot.
+
+        The restore targets the same backend the snapshot was taken from. A V1
+        snapshot restores as a V1 sandbox, a V2 snapshot as a V2 sandbox.
+        """
+        ...
+
+    @staticmethod
+    async def _experimental_from_snapshot_v2(
+        snapshot: modal.snapshot._SandboxSnapshot,
+        client: modal.client._Client,
+        *,
+        override_type: int,
+        name_override: typing.Optional[str],
+    ) -> _Sandbox: ...
     @property
     def filesystem(self) -> modal.sandbox_fs._SandboxFilesystem:
         """Namespace for Sandbox filesystem APIs."""
@@ -1768,6 +1810,7 @@ class Sandbox(modal.object.Object):
             verbose: bool = False,
             custom_domain: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
+            _experimental_enable_snapshot: bool = False,
         ) -> Sandbox:
             """Create a sandbox using the V2 backend.
 
@@ -1783,8 +1826,9 @@ class Sandbox(modal.object.Object):
             tuple that additionally sets a hard limit (fractional CPU cores; memory
             in MiB), matching `Sandbox.create()`.
 
-            Features like memory snapshots, network file systems, and GPUs are not
-            supported.
+            Pass `_experimental_enable_snapshot=True` to create a sandbox that can be
+            snapshotted with `._experimental_snapshot()`. Features like network
+            file systems and GPUs are not supported.
 
             Set `i6pn=True` to enable private IPv6 networking so sandboxes in the same
             workspace can address each other directly at their `i6pn.modal.local`
@@ -1837,6 +1881,7 @@ class Sandbox(modal.object.Object):
             verbose: bool = False,
             custom_domain: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
+            _experimental_enable_snapshot: bool = False,
         ) -> Sandbox:
             """Create a sandbox using the V2 backend.
 
@@ -1852,8 +1897,9 @@ class Sandbox(modal.object.Object):
             tuple that additionally sets a hard limit (fractional CPU cores; memory
             in MiB), matching `Sandbox.create()`.
 
-            Features like memory snapshots, network file systems, and GPUs are not
-            supported.
+            Pass `_experimental_enable_snapshot=True` to create a sandbox that can be
+            snapshotted with `._experimental_snapshot()`. Features like network
+            file systems and GPUs are not supported.
 
             Set `i6pn=True` to enable private IPv6 networking so sandboxes in the same
             workspace can address each other directly at their `i6pn.modal.local`
@@ -2177,6 +2223,59 @@ class Sandbox(modal.object.Object):
 
     _experimental_set_outbound_network_policy: ___experimental_set_outbound_network_policy_spec
 
+    class ___experimental_get_exit_snapshot_spec(typing_extensions.Protocol):
+        def __call__(self, /, timeout: typing.Optional[float] = 60) -> modal.image.Image:
+            """Get the exit filesystem snapshot image.
+
+            Args:
+                timeout: Client-side deadline in seconds (default 60). Use `None` to
+                    poll until the snapshot reaches a terminal state. Use `0` to
+                    perform an immediate check.
+
+            Returns:
+                The exit snapshot Image.
+
+            Raises:
+                InvalidError: If `timeout` is negative, or if exit snapshot is not
+                    enabled for the sandbox.
+                TimeoutError: If `timeout` elapses before the snapshot reaches a
+                    terminal state. This includes `timeout=0` when the snapshot is
+                    still pending.
+                SnapshotCreationError: If no exit snapshot image will be produced.
+                NotFoundError: If the sandbox does not exist.
+                PermissionDeniedError: If the caller cannot access the sandbox.
+                InternalError: If persisted snapshot state is malformed.
+                ServiceError: If a transient client/server communication failure occurs.
+            """
+            ...
+
+        async def aio(self, /, timeout: typing.Optional[float] = 60) -> modal.image.Image:
+            """Get the exit filesystem snapshot image.
+
+            Args:
+                timeout: Client-side deadline in seconds (default 60). Use `None` to
+                    poll until the snapshot reaches a terminal state. Use `0` to
+                    perform an immediate check.
+
+            Returns:
+                The exit snapshot Image.
+
+            Raises:
+                InvalidError: If `timeout` is negative, or if exit snapshot is not
+                    enabled for the sandbox.
+                TimeoutError: If `timeout` elapses before the snapshot reaches a
+                    terminal state. This includes `timeout=0` when the snapshot is
+                    still pending.
+                SnapshotCreationError: If no exit snapshot image will be produced.
+                NotFoundError: If the sandbox does not exist.
+                PermissionDeniedError: If the caller cannot access the sandbox.
+                InternalError: If persisted snapshot state is malformed.
+                ServiceError: If a transient client/server communication failure occurs.
+            """
+            ...
+
+    _experimental_get_exit_snapshot: ___experimental_get_exit_snapshot_spec
+
     class __snapshot_filesystem_spec(typing_extensions.Protocol):
         def __call__(self, /, timeout: int = 55, *, ttl: typing.Optional[int] = 2592000) -> modal.image.Image:
             """Snapshot the filesystem of the Sandbox.
@@ -2802,7 +2901,14 @@ class Sandbox(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             *,
             name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
-        ): ...
+        ):
+            """Restore a Sandbox from a memory snapshot.
+
+            The restore targets the same backend the snapshot was taken from. A V1
+            snapshot restores as a V1 sandbox, a V2 snapshot as a V2 sandbox.
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -2810,10 +2916,38 @@ class Sandbox(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             *,
             name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
-        ): ...
+        ):
+            """Restore a Sandbox from a memory snapshot.
+
+            The restore targets the same backend the snapshot was taken from. A V1
+            snapshot restores as a V1 sandbox, a V2 snapshot as a V2 sandbox.
+            """
+            ...
 
     _experimental_from_snapshot: typing.ClassVar[___experimental_from_snapshot_spec]
 
+    class ___experimental_from_snapshot_v2_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            snapshot: modal.snapshot.SandboxSnapshot,
+            client: modal.client.Client,
+            *,
+            override_type: int,
+            name_override: typing.Optional[str],
+        ) -> Sandbox: ...
+        async def aio(
+            self,
+            /,
+            snapshot: modal.snapshot.SandboxSnapshot,
+            client: modal.client.Client,
+            *,
+            override_type: int,
+            name_override: typing.Optional[str],
+        ) -> Sandbox: ...
+
+    _experimental_from_snapshot_v2: typing.ClassVar[___experimental_from_snapshot_v2_spec]
+
     @property
     def filesystem(self) -> modal.sandbox_fs.SandboxFilesystem:
         """Namespace for Sandbox filesystem APIs."""