modAL 1.6.3.dev5__py3-none-any.whl → 1.6.3.dev6__py3-none-any.whl

modal/_utils/grpc_testing.py

@@ -116,7 +116,7 @@ class InterceptionContext:
         """Adds one response payload to an expected queue of responses for a method.
 
         These responses will be used once each instead of calling the MockServicer's
-        implementation of the method.
+        implementation of the method. An exception payload is raised instead of being sent.
 
         The interception context will throw an exception on exit if not all of the added
         responses have been consumed.
@@ -184,6 +184,8 @@ class InterceptionContext:
         async def responder(servicer_self, stream):
             await stream.recv_message()  # get the input message so we can track that
             for msg in next_response_messages:
+                if isinstance(msg, Exception):
+                    raise msg
                 await stream.send_message(msg)
 
         return responder

modal/builder/PREVIEW.txt

@@ -1,21 +1,18 @@
-aiohappyeyeballs==2.6.1
-aiohttp==3.12.7
-aiosignal==1.3.2
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.5
+aiosignal==1.4.0
 async-timeout==5.0.1 ; python_version < "3.11"
-attrs==25.3.0
-cbor2==5.7.0
-certifi==2025.4.26
-frozenlist==1.6.0
-grpclib==0.4.8 ; python_version < "3.14"
-grpclib==0.4.9 ; python_version >= "3.14"
-h2==4.2.0
-hpack==4.1.0
+attrs==26.1.0
+cbor2==5.9.0
+certifi==2026.10.19
+frozenlist==1.8.0
+grpclib==0.4.9
+h2==4.4.1
+hpack==4.2.0
 hyperframe==6.1.0
-idna==3.10
-multidict==6.4.4
-propcache==0.3.1
-protobuf==6.31.1 ; python_version <= "3.14"
-protobuf==7.35.1 ; python_version >= "3.15"
-typing_extensions==4.13.2 ; python_version <= "3.14"
-typing_extensions==4.16.0 ; python_version >= "3.15"
-yarl==1.20.0
+idna==3.20
+multidict==7.1.0
+propcache==0.5.4
+protobuf==7.36.2
+typing_extensions==4.16.0
+yarl==1.25.1

modal/client.pyi

@@ -80,7 +80,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.3.dev5",
+        version: str = "1.6.3.dev6",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):
@@ -290,7 +290,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.3.dev5",
+        version: str = "1.6.3.dev6",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):

modal/sandbox/_common.py

@@ -386,7 +386,7 @@ class SandboxCreateArgs:
     secrets: Collection[_Secret] | None = None
     env: dict[str, str | None] | None = None
     name: str | None = None
-    timeout: int = 300
+    timeout: int | None = 300
     idle_timeout: int | None = None
     workdir: str | None = None
     gpu: str | None = None
@@ -417,6 +417,7 @@ class SandboxCreateArgs:
     custom_domain: str | None = None
     include_oidc_identity_token: bool = False
     runtime: SandboxRuntime | None = None
+    persistent: bool = False
 
 
 class SandboxCreateCommon:
@@ -428,6 +429,8 @@ class SandboxCreateCommon:
 
     def __init__(self, create_args: SandboxCreateArgs, *, secrets: Sequence[_Secret]) -> None:
         a = create_args
+        if a.timeout is None:
+            raise InvalidError("`timeout=None` is only supported for experimental persistent Sandboxes.")
         _validate_exec_args(a.args)
         if a.name is not None:
             check_object_name(a.name, "Sandbox")
@@ -452,6 +455,7 @@ class SandboxCreateCommon:
             raise InvalidError("`inbound_cidr_allowlist` cannot be used when `block_network` is enabled")
 
         self.create_args = a
+        self.timeout = a.timeout
         self.secrets = secrets
         self.image = a.image or _default_image
         self.network_file_systems = validate_network_file_systems(a.network_file_systems)
@@ -503,7 +507,7 @@ class SandboxCreateCommon:
             secret_ids=[secret.object_id for secret in self.secrets],
             # Ephemeral disk requests are not supported on Sandboxes.
             resources=convert_fn_config_to_resources_config(cpu=a.cpu, memory=a.memory, gpu=a.gpu, ephemeral_disk=None),
-            timeout_secs=a.timeout,
+            timeout_secs=self.timeout,
             idle_timeout_secs=a.idle_timeout,
             workdir=a.workdir,
             cloud_provider_str=a.cloud if a.cloud else None,  # pyright: ignore[reportArgumentType]
@@ -637,6 +641,10 @@ class SandboxImpl(Protocol):
         """
         ...
 
+    def clone(self) -> "SandboxImpl":
+        """Create an implementation of the same type for another handle to the same Sandbox."""
+        ...
+
     @classmethod
     async def lookup_by_name(
         cls, client: _Client, req: api_pb2.SandboxGetFromNameRequest
@@ -674,6 +682,10 @@ class SandboxImpl(Protocol):
 
     async def terminate(self) -> None: ...
 
+    async def pause(self) -> None: ...
+
+    async def resume(self) -> None: ...
+
     async def close(self) -> None:
         """Release connections held for the Sandbox once in-flight operations complete."""
         ...
@@ -907,6 +919,9 @@ async def snapshot_filesystem_via_tcr(
     return _Image._new_hydrated(res.image_id, client, None)
 
 
+_PERSISTENT_ONLY_MESSAGE = "`{}` requires a persistent Sandbox, created with `_experimental_persistent=True`."
+
+
 async def mount_image_via_tcr(
     impl: SandboxImpl,
     path: PurePosixPath | str,

modal/sandbox/_impl_persistent.py

@@ -0,0 +1,470 @@
+# Copyright Modal Labs 2026
+"""Persistent Sandboxes, managed by the `PersistentSandbox*` control-plane RPCs.
+
+A persistent Sandbox runs as a sequence of regular V2 Sandboxes, its sessions. The control plane starts each
+session from the exit snapshot of the previous one.
+"""
+
+import asyncio
+import copy
+import dataclasses
+import time
+import weakref
+from collections.abc import Awaitable, Callable, Collection, Sequence
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
+
+from grpclib import GRPCError, Status
+
+from modal_proto import api_pb2, task_command_router_pb2 as sr_pb2
+
+from .._image import _Image
+from .._outbound_policy import _OutboundPolicy
+from .._resolver import Resolver
+from .._tunnel import Tunnel
+from ..client import _Client
+from ..cloud_bucket_mount import _CloudBucketMount, cloud_bucket_mounts_to_proto
+from ..config import logger
+from ..container_process import _ContainerProcess
+from ..exception import ClientClosed, InvalidError, SandboxTerminatedError
+from ..io_streams import (
+    StreamReader,
+    StreamWriter,
+    _StreamReaderThroughSandboxCommandRouterParams,
+    _StreamWriterThroughCommandRouterSandboxParams,
+)
+from ..secret import _resolvable_secrets, _Secret, _secret_sources
+from ..stream_type import StreamType
+from ._common import SandboxCreateArgs, SandboxCreateCommon, SandboxImpl, command_router, sandbox_create_context
+from ._impl_v2 import SandboxImplV2, auth_metadata
+from ._snapshot import _SandboxSnapshot
+from ._task_command_router_client import TaskCommandRouterClient
+
+if TYPE_CHECKING:
+    import modal.app
+
+_T = TypeVar("_T")
+
+# Errors caused by the caller rather than by the session, which a new session can't fix.
+_NON_RECOVERABLE_ERRORS = (InvalidError, ClientClosed)
+
+# Lifetime limits of each session. A session that hits one is paused, and resumed on next use.
+PERSISTENT_SANDBOX_SESSION_TIMEOUT = 60 * 60
+PERSISTENT_SANDBOX_SESSION_IDLE_TIMEOUT = 5 * 60
+
+# How long to retry resuming while the previous session is still saving its exit snapshot.
+_RESUME_RETRY_TIMEOUT = 120.0
+_RESUME_RETRY_INTERVAL = 1.0
+
+# How often `wait()` checks whether the persistent Sandbox has been terminated.
+_WAIT_POLL_INTERVAL = 1.0
+
+_TERMINATED_RESULT = api_pb2.GenericResult(status=api_pb2.GenericResult.GENERIC_STATUS_TERMINATED)
+
+
+class SandboxImplPersistent:
+    """Backs a persistent Sandbox, whose object ID is the ID of its first session.
+
+    Operations are forwarded to the current session. When one fails and the Sandbox hasn't been terminated
+    through this handle, the control plane is asked for the running session, resuming the Sandbox from its
+    latest exit snapshot if there is none. The operation is then retried once on the new session.
+    """
+
+    def __init__(
+        self,
+        client: _Client,
+        sandbox_id: str,
+        *,
+        result: api_pb2.GenericResult | None = None,
+        persistent_sandbox_id: str = "",
+        session: SandboxImplV2 | None = None,
+    ) -> None:
+        self.client = client
+        self.sandbox_id = sandbox_id
+        self.result = result
+        self._persistent_sandbox_id = persistent_sandbox_id
+        self._session = session if session is not None else SandboxImplV2(client, sandbox_id)
+        self._replace_lock: asyncio.Lock | None = None
+        self._terminated = result is not None
+
+    @property
+    def _delegate(self) -> SandboxImplV2:
+        return self._session
+
+    @property
+    def _client(self) -> _Client:
+        return self.client
+
+    @classmethod
+    async def create(
+        cls, create_args: SandboxCreateArgs, *, app: "modal.app._App | None", client: _Client | None
+    ) -> "tuple[SandboxImpl, api_pb2.SandboxHandleMetadata]":
+        if create_args.timeout is not None or create_args.idle_timeout is not None:
+            raise InvalidError("Persistent Sandboxes require `timeout=None` and don't support `idle_timeout`.")
+        create_args = dataclasses.replace(
+            create_args,
+            timeout=PERSISTENT_SANDBOX_SESSION_TIMEOUT,
+            idle_timeout=PERSISTENT_SANDBOX_SESSION_IDLE_TIMEOUT,
+        )
+        if create_args.name is not None:
+            raise InvalidError("Named persistent Sandboxes are not supported yet.")
+        if create_args.gpu is not None or create_args.network_file_systems or create_args.pty_info is not None:
+            raise InvalidError("GPUs, network file systems and PTYs are not supported by persistent Sandboxes yet.")
+        if create_args.enable_snapshot:
+            raise InvalidError("Memory snapshots are not supported by persistent Sandboxes.")
+        if create_args.env or create_args.tags:
+            raise InvalidError("`env` and `tags` are not supported by persistent Sandboxes yet.")
+
+        secrets = create_args.secrets or []
+        common = SandboxCreateCommon(create_args, secrets=_resolvable_secrets(secrets))
+        async with sandbox_create_context(app, client) as (client, load_context):
+            await common.load_dependencies(Resolver(), load_context, load_ephemeral_bucket_secrets=False)
+            cloud_bucket_mount_protos, cloud_bucket_credentials = cloud_bucket_mounts_to_proto(
+                common.cloud_bucket_mounts, split_ephemeral_credentials=True
+            )
+            if cloud_bucket_credentials or any(source.HasField("env") for source in _secret_sources(secrets)):
+                raise InvalidError("Ephemeral credentials are not supported by persistent Sandboxes yet.")
+            req = api_pb2.PersistentSandboxCreateRequest(
+                app_id=load_context.app_id or "",
+                definition=common.definition(cloud_bucket_mounts=cloud_bucket_mount_protos),
+            )
+            resp = await client._stub.PersistentSandboxCreate(req, metadata=await auth_metadata(client))
+            app_id = load_context.app_id or ""
+        impl = cls(client, resp.sandbox_id, persistent_sandbox_id=resp.persistent_sandbox_id)
+        return impl, api_pb2.SandboxHandleMetadata(app_id=app_id)
+
+    # Persistent Sandboxes are only created through `create`, and can't be looked up yet.
+
+    @classmethod
+    async def lookup_by_name(cls, *args: Any, **kwargs: Any) -> api_pb2.SandboxGetFromNameResponse:
+        raise NotImplementedError
+
+    @classmethod
+    async def lookup_by_id(cls, *args: Any, **kwargs: Any) -> api_pb2.SandboxWaitResponse:
+        raise NotImplementedError
+
+    @classmethod
+    async def list_page(cls, *args: Any, **kwargs: Any) -> api_pb2.SandboxListResponse:
+        raise NotImplementedError
+
+    @classmethod
+    async def restore_from_memory_snapshot(
+        cls, *args: Any, **kwargs: Any
+    ) -> "tuple[SandboxImpl, api_pb2.SandboxHandleMetadata]":
+        raise NotImplementedError
+
+    def clone(self) -> "SandboxImplPersistent":
+        return copy.copy(self)
+
+    def make_stdio(self, check_open: Callable[[], None]) -> tuple[StreamReader[str], StreamReader[str], StreamWriter]:
+        """Create stdio streams of the entrypoint of whichever session is current when they connect."""
+        weak_self = weakref.ref(self)
+
+        async def resolve_router() -> tuple[str, TaskCommandRouterClient]:
+            this = weak_self()
+            if this is None:
+                raise RuntimeError("Sandbox was garbage collected before its stdio reader connected")
+            return await command_router(this)
+
+        def reader(file_descriptor: "api_pb2.FileDescriptor.ValueType") -> StreamReader[str]:
+            return StreamReader(
+                _StreamReaderThroughSandboxCommandRouterParams(
+                    file_descriptor=file_descriptor, sandbox_id=self.sandbox_id, resolve_router=resolve_router
+                ),
+                by_line=True,
+            )
+
+        stdin = StreamWriter(
+            _StreamWriterThroughCommandRouterSandboxParams(resolve_router=resolve_router, check_open=check_open)
+        )
+        return reader(api_pb2.FILE_DESCRIPTOR_STDOUT), reader(api_pb2.FILE_DESCRIPTOR_STDERR), stdin
+
+    # Session replacement
+
+    async def _run(self, op: Callable[[SandboxImplV2], Awaitable[_T]]) -> _T:
+        """Run `op` on the session, switching to the running session and retrying once if it fails."""
+        session = self._delegate
+        try:
+            return await op(session)
+        except _NON_RECOVERABLE_ERRORS:
+            raise
+        except Exception as exc:
+            if self._terminated:
+                # A terminated persistent Sandbox is stopped for good, so it isn't resumed on use.
+                raise
+            replacement = await self._replace_session(session)
+            if replacement is None:
+                raise
+            logger.debug(f"Retrying operation on persistent Sandbox {self._persistent_sandbox_id} after: {exc!r}")
+            return await op(replacement)
+
+    async def _get_running_session_id(self) -> str:
+        req = api_pb2.PersistentSandboxGetRequest(persistent_sandbox_id=self._persistent_sandbox_id)
+        resp = await self._client._stub.PersistentSandboxGet(req, metadata=await auth_metadata(self._client))
+        return resp.sandbox_id
+
+    async def _resume_session(self) -> str:
+        """Resume the persistent Sandbox, returning the ID of its running session."""
+        req = api_pb2.PersistentSandboxResumeRequest(persistent_sandbox_id=self._persistent_sandbox_id)
+        deadline = time.monotonic() + _RESUME_RETRY_TIMEOUT
+        while True:
+            try:
+                resp = await self._client._stub.PersistentSandboxResume(req, metadata=await auth_metadata(self._client))
+                return resp.sandbox_id
+            except GRPCError as exc:
+                # UNAVAILABLE means the previous session is still pausing or another resume is in progress.
+                if exc.status != Status.UNAVAILABLE or time.monotonic() > deadline:
+                    raise
+            await asyncio.sleep(_RESUME_RETRY_INTERVAL)
+
+    async def _replace_session(self, failed: SandboxImplV2 | None, *, resume: bool = True) -> SandboxImplV2 | None:
+        """Switch from the `failed` session, or return None if it is still the running session."""
+        # Lazily create the lock on the event loop that first uses the Sandbox.
+        if self._replace_lock is None:
+            self._replace_lock = asyncio.Lock()
+        async with self._replace_lock:
+            if self._session is not failed:
+                # A concurrent operation has already replaced the session.
+                return self._session
+
+            session_id = await self._get_running_session_id()
+            if failed is not None and session_id == failed.sandbox_id:
+                return None
+            if not session_id:
+                if not resume:
+                    return None
+                session_id = await self._resume_session()
+            logger.debug(f"Switching persistent Sandbox {self._persistent_sandbox_id} to session {session_id}")
+            replacement = SandboxImplV2(self.client, session_id)
+            self._session = replacement
+            if failed is not None:
+                await failed.close()
+            return replacement
+
+    # Operations
+
+    async def close(self) -> None:
+        await self._session.close()
+
+    def _set_terminated_result(self) -> None:
+        self.result = _TERMINATED_RESULT
+
+    async def wait(self, raise_on_termination: bool) -> None:
+        # A persistent Sandbox keeps running across sessions, until it is terminated.
+        while not self._terminated:
+            await asyncio.sleep(_WAIT_POLL_INTERVAL)
+        self._set_terminated_result()
+        if raise_on_termination:
+            raise SandboxTerminatedError()
+
+    async def poll(self) -> None:
+        if self._terminated:
+            self._set_terminated_result()
+        else:
+            self.result = None
+
+    async def terminate(self) -> None:
+        req = api_pb2.PersistentSandboxTerminateRequest(persistent_sandbox_id=self._persistent_sandbox_id)
+        await self._client._stub.PersistentSandboxTerminate(req, metadata=await auth_metadata(self._client))
+        self._terminated = True
+        self._set_terminated_result()
+
+    async def pause(self) -> None:
+        """Stop the current session, which saves its exit snapshot for the next `resume`."""
+        self._check_not_terminated()
+        session = self._delegate
+        await session.terminate()
+        await session.wait(raise_on_termination=False)
+
+    async def resume(self) -> None:
+        """Start a session from the latest exit snapshot, unless one is already running."""
+        self._check_not_terminated()
+        session = self._delegate
+        session_id = await self._resume_session()
+        if session_id != session.sandbox_id:
+            self._session = SandboxImplV2(self.client, session_id)
+            await session.close()
+
+    def _check_not_terminated(self) -> None:
+        if self._terminated:
+            raise InvalidError(f"Persistent Sandbox {self._persistent_sandbox_id} has been terminated.")
+
+    async def tunnels(self, timeout: int) -> dict[int, Tunnel]:
+        return await self._run(lambda d: d.tunnels(timeout))
+
+    async def get_task_id(
+        self, raise_if_task_complete: bool = False, timeout: float | None = None, retry_transient: bool = False
+    ) -> str:
+        return await self._run(
+            lambda d: d.get_task_id(
+                raise_if_task_complete=raise_if_task_complete, timeout=timeout, retry_transient=retry_transient
+            )
+        )
+
+    async def resolve_task_id_for_logs(self) -> str:
+        return await self._delegate.resolve_task_id_for_logs()
+
+    async def get_exit_snapshot(self, timeout: float | None) -> _Image:
+        return await self._delegate.get_exit_snapshot(timeout)
+
+    async def snapshot_memory(self) -> _SandboxSnapshot:
+        raise NotImplementedError("Memory snapshots aren't supported for persistent Sandboxes.")
+
+    async def get_command_router_client(self, task_id: str) -> TaskCommandRouterClient:
+        # The task ID belongs to the current delegate, so this can't be retried on a replacement.
+        return await self._delegate.get_command_router_client(task_id)
+
+    async def get_tags(self) -> dict[str, str]:
+        raise NotImplementedError("Tags aren't supported for persistent Sandboxes yet.")
+
+    async def set_tags(self, tags: dict[str, str]) -> None:
+        raise NotImplementedError("Tags aren't supported for persistent Sandboxes yet.")
+
+    async def set_name(self, name: str) -> None:
+        raise InvalidError("The name of a persistent Sandbox can't be changed.")
+
+    async def create_connect_token(
+        self, req: api_pb2.SandboxCreateConnectTokenRequest
+    ) -> api_pb2.SandboxCreateConnectTokenResponse:
+        def create(d: SandboxImplV2) -> Awaitable[api_pb2.SandboxCreateConnectTokenResponse]:
+            delegate_req = api_pb2.SandboxCreateConnectTokenRequest()
+            delegate_req.CopyFrom(req)
+            delegate_req.sandbox_id = d.sandbox_id
+            return d.create_connect_token(delegate_req)
+
+        return await self._run(create)
+
+    async def wait_until_ready(self, timeout: int) -> None:
+        await self._run(lambda d: d.wait_until_ready(timeout))
+
+    async def set_network_access(self, network_access: api_pb2.NetworkAccess) -> None:
+        raise NotImplementedError("Updating network access isn't supported for persistent Sandboxes yet.")
+
+    async def update_outbound_policy(self, outbound_policy: _OutboundPolicy) -> None:
+        raise NotImplementedError("Updating the outbound policy isn't supported for persistent Sandboxes yet.")
+
+    async def snapshot_filesystem(self, timeout: int, *, ttl: int | None, container_id: str = "") -> _Image:
+        return await self._run(lambda d: d.snapshot_filesystem(timeout, ttl=ttl, container_id=container_id))
+
+    async def mount_image(
+        self,
+        path: PurePosixPath | str,
+        image_id: str,
+        *,
+        encryption_key: bytes | None,
+        container_id: str = "",
+    ) -> None:
+        raise NotImplementedError("Mounting images isn't supported for persistent Sandboxes yet.")
+
+    async def unmount_image(self, path: PurePosixPath | str, *, container_id: str = "") -> None:
+        raise NotImplementedError("Mounting images isn't supported for persistent Sandboxes yet.")
+
+    async def snapshot_directory(
+        self,
+        path: PurePosixPath | str,
+        *,
+        timeout: int,
+        ttl: int | None,
+        encryption_key: bytes | None,
+        container_id: str = "",
+    ) -> _Image:
+        return await self._run(
+            lambda d: d.snapshot_directory(
+                path, timeout=timeout, ttl=ttl, encryption_key=encryption_key, container_id=container_id
+            )
+        )
+
+    async def reload_volumes(self, *, timeout: int, container_id: str = "") -> None:
+        await self._run(lambda d: d.reload_volumes(timeout=timeout, container_id=container_id))
+
+    async def exec(
+        self,
+        *args: str,
+        pty_info: api_pb2.PTYInfo | None,
+        stdout: StreamType,
+        stderr: StreamType,
+        timeout: int | None,
+        workdir: str | None,
+        env: dict[str, str | None] | None,
+        secrets: Collection[_Secret] | None,
+        text: bool,
+        bufsize: Literal[-1, 1],
+        container_id: str | None,
+    ) -> _ContainerProcess[bytes] | _ContainerProcess[str]:
+        return await self._run(
+            lambda d: d.exec(
+                *args,
+                pty_info=pty_info,
+                stdout=stdout,
+                stderr=stderr,
+                timeout=timeout,
+                workdir=workdir,
+                env=env,
+                secrets=secrets,
+                text=text,
+                bufsize=bufsize,
+                container_id=container_id,
+            )
+        )
+
+    # Sidecar containers
+
+    def validate_sidecar_create(
+        self,
+        *,
+        cloud_bucket_mounts: Sequence[tuple[str, _CloudBucketMount]],
+        has_proxy: bool,
+        include_oidc_identity_token: bool,
+    ) -> None:
+        self._delegate.validate_sidecar_create(
+            cloud_bucket_mounts=cloud_bucket_mounts,
+            has_proxy=has_proxy,
+            include_oidc_identity_token=include_oidc_identity_token,
+        )
+
+    async def create_sidecar(
+        self,
+        *args: str,
+        name: str,
+        image_id: str,
+        secret_ids: Sequence[str],
+        secret_sources: Sequence[api_pb2.SecretSource],
+        workdir: str | None,
+        volume_mounts: Sequence[api_pb2.VolumeMount],
+        cloud_bucket_mounts: Sequence[tuple[str, _CloudBucketMount]],
+        network_access: api_pb2.NetworkAccess,
+        include_oidc_identity_token: bool,
+        proxy_id: str | None,
+        pty_info: api_pb2.PTYInfo | None,
+        memory_reserve_consume_mib: int | None,
+    ) -> tuple[str, str]:
+        return await self._run(
+            lambda d: d.create_sidecar(
+                *args,
+                name=name,
+                image_id=image_id,
+                secret_ids=secret_ids,
+                secret_sources=secret_sources,
+                workdir=workdir,
+                volume_mounts=volume_mounts,
+                cloud_bucket_mounts=cloud_bucket_mounts,
+                network_access=network_access,
+                include_oidc_identity_token=include_oidc_identity_token,
+                proxy_id=proxy_id,
+                pty_info=pty_info,
+                memory_reserve_consume_mib=memory_reserve_consume_mib,
+            )
+        )
+
+    async def get_sidecar(self, name: str, include_terminated: bool) -> sr_pb2.TaskContainerInfo:
+        return await self._run(lambda d: d.get_sidecar(name, include_terminated))
+
+    async def list_sidecars(self, include_terminated: bool) -> list[sr_pb2.TaskContainerInfo]:
+        return await self._run(lambda d: d.list_sidecars(include_terminated))
+
+    async def wait_sidecar(self, container_id: str, timeout: float) -> api_pb2.GenericResult | None:
+        # Sidecar containers don't carry over to a replacement delegate.
+        return await self._delegate.wait_sidecar(container_id, timeout)
+
+    async def terminate_sidecar(self, container_id: str) -> None:
+        await self._delegate.terminate_sidecar(container_id)

modal/sandbox/_impl_v1.py

@@ -40,6 +40,7 @@ from ..io_streams import (
 from ..secret import _Secret
 from ..stream_type import StreamType
 from ._common import (
+    _PERSISTENT_ONLY_MESSAGE,
     _TASK_ID_POLL_INTERVAL,
     ExitSnapshotPoll,
     SandboxCreateArgs,
@@ -124,6 +125,9 @@ class SandboxImplV1:
     def _client(self) -> _Client:
         return self.client
 
+    def clone(self) -> "SandboxImplV1":
+        return type(self)(self.client, self.sandbox_id, result=self.result)
+
     @classmethod
     async def create(
         cls, create_args: SandboxCreateArgs, *, app: "modal.app._App | None", client: _Client | None
@@ -289,6 +293,12 @@ class SandboxImplV1:
         req = api_pb2.SandboxTerminateRequest(sandbox_id=self.sandbox_id)
         await self.client._stub.SandboxTerminate(req)
 
+    async def pause(self) -> None:
+        raise NotImplementedError(_PERSISTENT_ONLY_MESSAGE.format("_experimental_pause()"))
+
+    async def resume(self) -> None:
+        raise NotImplementedError(_PERSISTENT_ONLY_MESSAGE.format("_experimental_resume()"))
+
     async def snapshot_filesystem(self, timeout: int, *, ttl: int | None, container_id: str = "") -> _Image:
         if not container_id and os.environ.get("MODAL_USE_LEGACY_FILESYSTEM_SNAPSHOT") == "1":
             if ttl != DEFAULT_SNAPSHOT_TTL:

modal/sandbox/_impl_v2.py

@@ -32,6 +32,7 @@ from ..io_streams import (
 from ..secret import _resolvable_secrets, _Secret, _secret_sources
 from ..stream_type import StreamType
 from ._common import (
+    _PERSISTENT_ONLY_MESSAGE,
     _TASK_ID_POLL_INTERVAL,
     ExitSnapshotPoll,
     SandboxCreateArgs,
@@ -147,6 +148,9 @@ class SandboxImplV2:
     def _client(self) -> _Client:
         return self.client
 
+    def clone(self) -> "SandboxImplV2":
+        return type(self)(self.client, self.sandbox_id, result=self.result)
+
     @classmethod
     async def create(
         cls, create_args: SandboxCreateArgs, *, app: "modal.app._App | None", client: _Client | None
@@ -351,6 +355,12 @@ class SandboxImplV2:
         req = api_pb2.SandboxTerminateRequest(sandbox_id=self.sandbox_id)
         await self.client._stub.SandboxTerminateV2(req, metadata=await self._metadata())
 
+    async def pause(self) -> None:
+        raise NotImplementedError(_PERSISTENT_ONLY_MESSAGE.format("_experimental_pause()"))
+
+    async def resume(self) -> None:
+        raise NotImplementedError(_PERSISTENT_ONLY_MESSAGE.format("_experimental_resume()"))
+
     def _create_sidecar_via_control_plane(self) -> bool:
         # Opt out via the `use_control_plane_sidecar_create` config setting to create
         # sidecars over the task command router instead.

modal/sandbox/_sandbox.py

@@ -46,6 +46,7 @@ from ._common import (
     default_pty_info,
 )
 from ._filesystem import _SandboxFilesystem
+from ._impl_persistent import SandboxImplPersistent
 from ._impl_v1 import SandboxImplV1, command_router_access_fetcher as v1_command_router_access_fetcher
 from ._impl_v2 import SandboxImplV2, command_router_access_fetcher as v2_command_router_access_fetcher
 from ._sidecar import _SidecarManager
@@ -69,6 +70,8 @@ def impl_class_for_sandbox_id(sandbox_id: str) -> type[SandboxImpl]:
 
 def impl_class_for_create_args(create_args: SandboxCreateArgs) -> type[SandboxImpl]:
     """Select the implementation that creates the Sandbox described by `create_args`."""
+    if create_args.persistent:
+        return SandboxImplPersistent
     if create_args.gpu is not None or create_args.network_file_systems or create_args.pty_info is not None:
         # GPUs, network file systems, and PTYs are not supported on V2, so those calls use the V1
         # backend regardless of the setting.
@@ -183,7 +186,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         env: dict[str, str | None] | None = None,
         secrets: Collection[_Secret] | None = None,
         network_file_systems: dict[str | os.PathLike, _NetworkFileSystem] = {},
-        timeout: int = 300,
+        timeout: int | None = 300,
         idle_timeout: int | None = None,
         workdir: str | None = None,
         gpu: str | None = None,
@@ -209,6 +212,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         verbose: bool = False,
         experimental_options: dict[str, Any] | None = None,
         _experimental_enable_snapshot: bool = False,
+        _experimental_persistent: bool = False,
         client: _Client | None = None,
         environment_name: str | None = None,  # *DEPRECATED*
         pty_info: api_pb2.PTYInfo | None = None,  # *DEPRECATED*
@@ -349,6 +353,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             custom_domain=custom_domain,
             include_oidc_identity_token=include_oidc_identity_token,
             runtime=runtime,
+            persistent=_experimental_persistent,
         )
         impl, metadata = await impl_class_for_create_args(create_args).create(create_args, app=app, client=client)
         return _Sandbox._from_impl(impl, metadata)
@@ -495,8 +500,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         super()._initialize_from_other(other)
         self._attached = other._attached
         self._app_id = other._app_id
-        other_impl = other._impl
-        self._impl = type(other_impl)(other_impl.client, other_impl.sandbox_id, result=other_impl.result)
+        self._impl = other._impl.clone()
 
     def _initialize_from_empty(self):
         super()._initialize_from_empty()
@@ -1029,6 +1033,20 @@ class _Sandbox(_Object, type_prefix="sb"):
             return self.returncode
         return None
 
+    async def _experimental_pause(self) -> None:
+        """Stop the Sandbox's current container, keeping its state so it can be resumed.
+
+        Only supported for experimental persistent Sandboxes.
+        """
+        await self._impl.pause()
+
+    async def _experimental_resume(self) -> None:
+        """Resume a paused Sandbox from its saved state.
+
+        Only supported for experimental persistent Sandboxes.
+        """
+        await self._impl.resume()
+
     async def poll(self) -> int | None:
         """Check if the Sandbox has finished running.
 

modal/sandbox/sandbox.pyi

@@ -1333,7 +1333,7 @@ class Sandbox(modal.object.Object):
             network_file_systems: dict[
                 typing.Union[str, os.PathLike], modal.network_file_system.NetworkFileSystem
             ] = {},
-            timeout: int = 300,
+            timeout: typing.Optional[int] = 300,
             idle_timeout: typing.Optional[int] = None,
             workdir: typing.Optional[str] = None,
             gpu: typing.Optional[str] = None,
@@ -1362,6 +1362,7 @@ class Sandbox(modal.object.Object):
             verbose: bool = False,
             experimental_options: typing.Optional[dict[str, typing.Any]] = None,
             _experimental_enable_snapshot: bool = False,
+            _experimental_persistent: bool = False,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             pty_info: typing.Optional[modal_proto.api_pb2.PTYInfo] = None,
@@ -1457,7 +1458,7 @@ class Sandbox(modal.object.Object):
             network_file_systems: dict[
                 typing.Union[str, os.PathLike], modal.network_file_system.NetworkFileSystem
             ] = {},
-            timeout: int = 300,
+            timeout: typing.Optional[int] = 300,
             idle_timeout: typing.Optional[int] = None,
             workdir: typing.Optional[str] = None,
             gpu: typing.Optional[str] = None,
@@ -1486,6 +1487,7 @@ class Sandbox(modal.object.Object):
             verbose: bool = False,
             experimental_options: typing.Optional[dict[str, typing.Any]] = None,
             _experimental_enable_snapshot: bool = False,
+            _experimental_persistent: bool = False,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             pty_info: typing.Optional[modal_proto.api_pb2.PTYInfo] = None,
@@ -2582,6 +2584,40 @@ class Sandbox(modal.object.Object):
 
     terminate: __terminate_spec
 
+    class ___experimental_pause_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> None:
+            """Stop the Sandbox's current container, keeping its state so it can be resumed.
+
+            Only supported for experimental persistent Sandboxes.
+            """
+            ...
+
+        async def aio(self, /) -> None:
+            """Stop the Sandbox's current container, keeping its state so it can be resumed.
+
+            Only supported for experimental persistent Sandboxes.
+            """
+            ...
+
+    _experimental_pause: ___experimental_pause_spec
+
+    class ___experimental_resume_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> None:
+            """Resume a paused Sandbox from its saved state.
+
+            Only supported for experimental persistent Sandboxes.
+            """
+            ...
+
+        async def aio(self, /) -> None:
+            """Resume a paused Sandbox from its saved state.
+
+            Only supported for experimental persistent Sandboxes.
+            """
+            ...
+
+    _experimental_resume: ___experimental_resume_spec
+
     class __poll_spec(typing_extensions.Protocol):
         def __call__(self, /) -> typing.Optional[int]:
             """Check if the Sandbox has finished running.

{modal-1.6.3.dev5.dist-info → modal-1.6.3.dev6.dist-info}/METADATA

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

{modal-1.6.3.dev5.dist-info → modal-1.6.3.dev6.dist-info}/RECORD

@@ -39,7 +39,7 @@ modal/billing.py,sha256=E1-P_P8bJFLp-bTaggYd4BaaViImPB5UdtXiY8VeAZQ,390
 modal/billing.pyi,sha256=4m7VLYNS8IiJ2I3CJx0awvrOM6BILWRVLfdeqtAYr8M,7189
 modal/call_graph.py,sha256=XGALIDn1bLchWo_goyX23bcPjzCZcfqKUo8INIfDapo,1775
 modal/client.py,sha256=cstrL0wpXCZmcvRs7Sy3QRw9Vz8zkZy8NNk0tPe38sk,22852
-modal/client.pyi,sha256=wkF1jBOBV3bFWy8sI4U5HwBKIkFNyf1rjIFiI0E7sAA,23488
+modal/client.pyi,sha256=Sx1Q0OicQDZ2R9L-GLG0eDXWuF9c9tqV9aSvl6PyrLo,23488
 modal/cloud_bucket_mount.py,sha256=ZOg69dhIFcJcwim4JP-6s1tqwOYAfgS9806jRpspifw,7511
 modal/cloud_bucket_mount.pyi,sha256=HoPe_NG5jYdVfmTNY-ZJ3-C8Eo_FzJovl9orJRjkGbE,10252
 modal/cls.py,sha256=JfDAUMrkhasm26lK7kDUNarXZA_7AvZrymf7XNSGTDM,41777
@@ -127,7 +127,7 @@ modal/_utils/display_utils.py,sha256=5XyCCjnMAWeLEEqF0hiLSA6XrrNp-gvXVsLcngN6vAI
 modal/_utils/docker_utils.py,sha256=k8fkYT6G-X_B3iamjxiSpwSE-k58xGVHtsk2_gR7i2Q,4197
 modal/_utils/function_utils.py,sha256=dVCCnovfSlYssRuQh0Woq5oqX4Kj_tAK4vJ3USFNUFw,27537
 modal/_utils/git_utils.py,sha256=Lat_l4O4hwOYgylEtWup3hyqWT8D7JoCIjCflXcX8BE,3148
-modal/_utils/grpc_testing.py,sha256=udyK_wRXX_yc9eLt8mIZZqx12XlaiUqORxaGNvfI_MM,8697
+modal/_utils/grpc_testing.py,sha256=59FDtDsSeKrp9gmFI41dP_67yxxxydm06BhixpEnf2k,8828
 modal/_utils/grpc_utils.py,sha256=Gcl5EyEMEHMaMlGh90F63Oi1l9K6cnmeTCbGCouwJ-A,29998
 modal/_utils/hash_utils.py,sha256=WHuMRwmB4fnaM-qmyWXR87C2CinvLnmRoygSzsTEunA,3008
 modal/_utils/http_utils.py,sha256=TO9nnKR0Cc-iWCmkou56wJh9MHgNZwQMosK8WK-GD5Y,3133
@@ -153,7 +153,7 @@ modal/builder/2023.12.txt,sha256=OjsbXFkCSdkzzryZP82Q73osr5wxQ6EUzmGcK7twfkA,502
 modal/builder/2024.04.txt,sha256=6NnrbIE-mflwMyKyQ0tsWeY8XFE1kSW9oE8DVDoD8QU,544
 modal/builder/2024.10.txt,sha256=qD-5cVIVM9wXesJ6JC89Ew-3m2KjEElUz3jaw_MddRo,296
 modal/builder/2025.06.txt,sha256=90NzKtbJ32RrUtYiUv1XtJTDEaJ1SFcVpJXUE7Udle4,791
-modal/builder/PREVIEW.txt,sha256=9iN3AGZSovazQpxSHekDGDgjhroPz9Z-A6hZiZMJ7bs,544
+modal/builder/PREVIEW.txt,sha256=bBLNruBc0v4ulzCraMBVfVm-6kPku3Ag1nFnTy1kr_o,326
 modal/builder/README.md,sha256=9tK76KP0Uph7O0M5oUgsSwEZDj5y-dcUPsnpR0Sc-Ik,854
 modal/builder/base-images.json,sha256=5wyWfI3fQ51PH_dHvmXeTJPrKQBdi5B3DihQIWEXC4Q,1202
 modal/cli/__init__.py,sha256=6FRleWQxBDT19y7OayO4lBOzuL6Bs9r0rLINYYYbHwQ,769
@@ -198,18 +198,19 @@ modal/experimental/flash_server.py,sha256=iqxVoQij6aM58_h0la6Y_Vy3CCQj8iYmjzt79r
 modal/experimental/flash_server.pyi,sha256=LuIBqeOJ1NAapKWnJMRzzrwIHlIK2GcOLOI2r-z_QN0,1025
 modal/experimental/ipython.py,sha256=kJ6o9wkAY_MiSb7paewI7f1MJAeqdi8TX5pBdhr_mUI,2925
 modal/sandbox/__init__.py,sha256=wHE5KCHUaMSK_nNGbn852PI423v3Q4UQEsFpoqNqMMI,203
-modal/sandbox/_common.py,sha256=z82O2XIrRaeanCzNY4CBnk1X1MuRROJjDcFDtSDtaV8,46549
+modal/sandbox/_common.py,sha256=Kuibj5eS8upWLbSxtYdojPZtyCh0iLtdsAJ4RuK2Lk4,47098
 modal/sandbox/_filesystem.py,sha256=GdkMNVahPpUpfuY04HwWWwZyMID3bcut7PHXNWOIpYg,28299
-modal/sandbox/_impl_v1.py,sha256=AiFhTxEXb-B3TWRyDnIeO55UrMwEJAnDIhYf5h5oYrE,20513
-modal/sandbox/_impl_v2.py,sha256=O1NpY7c5qF-8RbypnWjdJxUfivxO-XAevDeluoLDtJs,25866
-modal/sandbox/_sandbox.py,sha256=K6GVvu4QW07gQWot8ZNX5wpsolYl-ZFVj3-RyfooopQ,61001
+modal/sandbox/_impl_persistent.py,sha256=PwlzsxfQYvsKPHDgmK1LnYSx7CIZSFKCtm_87YBSrnc,20182
+modal/sandbox/_impl_v1.py,sha256=Xy0Mp0_X9T7WAxY20R2NVaobXiC4ciPdsRLC0k4JnCM,20918
+modal/sandbox/_impl_v2.py,sha256=AUCRYVv-qm-eLEOqmsAacwXyRK7VTJ1faPJdwk18q5g,26271
+modal/sandbox/_sandbox.py,sha256=wvchpp_g1zotOMpMhzmiAovaAi6_q_f5_CF2aKzijQ8,61591
 modal/sandbox/_sidecar.py,sha256=k9SMe2V--gkj22fZRC3EN4GNPtdPFkrwJRxB7W4IFU4,21303
 modal/sandbox/_snapshot.py,sha256=8mB6FOecXEbgTC9dyogIEGCxTdjemuFsyfVFQyQ2Cp8,3105
 modal/sandbox/_task_command_router_client.py,sha256=ta_I2EsVruEkRE9YCaCHns4oCb_htz7aQIf0ZSp2wH0,55181
 modal/sandbox/sandbox.py,sha256=4ekghND9qUGf5wtIQH4mVa6PHGjHgY0UN5RKryOM05k,683
-modal/sandbox/sandbox.pyi,sha256=H3Itxk7z1hbrsRIF_zZP8mzAhMJ0pnrr1FvnWUIavZ4,137650
+modal/sandbox/sandbox.pyi,sha256=iWxqScPKLa6oo9vJGukv2XhuCOK0E-bj52trqetBBh8,138895
 modal/skills/modal/SKILL.md,sha256=Bm-0BPTYppJoeQzA-N-Re8L6-nKnV6gspJXMl4cD0P0,5490
-modal-1.6.3.dev5.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-1.6.3.dev6.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
 modal_docs/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/gen_cli_docs.py,sha256=9-b8vl2EsLWD9zJqpCK8IUi5h44Bjn3i3rSdedZV4bA,6415
 modal_docs/gen_cli_docs_main.py,sha256=UPGr7O1DYTIRLwfINe2rbdh89J3cPVTU1OWL-SjxnOQ,198
@@ -233,10 +234,10 @@ modal_proto/task_command_router_pb2.py,sha256=ysC0d8p3YxwyOpP3B-qDlvE81Yo4ntQiwi
 modal_proto/task_command_router_pb2.pyi,sha256=FDcd5t3ZCmQHUjefOzg07iglrgKYcBrzFvdKIWsEMHI,50628
 modal_proto/task_command_router_pb2_grpc.py,sha256=8iGUGwEVbqOsZWPJ7OsQ9OKUGaSCf9Dr2tvb04Ww6d4,44620
 modal_proto/task_command_router_pb2_grpc.pyi,sha256=26Fq9RQo09B9KLHsgdpRuw-I6Z4-2jrXLQkuDzB-moI,15097
-modal_version/__init__.py,sha256=TWF4iwbBqC0_KrbqBk0D3qxFSr5QGvt9zcsCBxWyQ88,120
+modal_version/__init__.py,sha256=ghBy3FJF-r7e--zuLA-Q_y9BZN24mOBqGseTPgAuR7c,120
 modal_version/__main__.py,sha256=nLUbubxKx7GXNzJIkTB7M7_u8080LyLM0IS0rzFkC_c,119
-modal-1.6.3.dev5.dist-info/METADATA,sha256=aOHUajhismM2QZ3trzMWEvzX3-X99wK7Yq0j8gN6S8A,2577
-modal-1.6.3.dev5.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-modal-1.6.3.dev5.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-1.6.3.dev5.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
-modal-1.6.3.dev5.dist-info/RECORD,,
+modal-1.6.3.dev6.dist-info/METADATA,sha256=QlL5GMEEPP1FCRpr-3VjtJM0hwz63Thio0szsMahzK4,2577
+modal-1.6.3.dev6.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+modal-1.6.3.dev6.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-1.6.3.dev6.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
+modal-1.6.3.dev6.dist-info/RECORD,,

modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2026
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.6.3.dev5"
+__version__ = "1.6.3.dev6"