modal 1.1.3.dev7__py3-none-any.whl → 1.1.4__py3-none-any.whl

modal/experimental/flash.pyi

@@ -1,13 +1,26 @@
 import modal.client
+import modal_proto.api_pb2
+import subprocess
 import typing
 import typing_extensions
 
 class _FlashManager:
-    def __init__(self, client: modal.client._Client, port: int, health_check_url: typing.Optional[str] = None):
+    def __init__(
+        self,
+        client: modal.client._Client,
+        port: int,
+        process: typing.Optional[subprocess.Popen] = None,
+        health_check_url: typing.Optional[str] = None,
+    ):
         """Initialize self.  See help(type(self)) for accurate signature."""
         ...
 
+    async def check_port_connection(self, process: typing.Optional[subprocess.Popen], timeout: int = 10): ...
     async def _start(self): ...
+    async def _drain_container(self):
+        """Background task that checks if we've encountered too many failures and drains the container if so."""
+        ...
+
     async def _run_heartbeat(self, host: str, port: int): ...
     def get_container_url(self): ...
     async def stop(self): ...
@@ -16,7 +29,19 @@ class _FlashManager:
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class FlashManager:
-    def __init__(self, client: modal.client.Client, port: int, health_check_url: typing.Optional[str] = None): ...
+    def __init__(
+        self,
+        client: modal.client.Client,
+        port: int,
+        process: typing.Optional[subprocess.Popen] = None,
+        health_check_url: typing.Optional[str] = None,
+    ): ...
+
+    class __check_port_connection_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /, process: typing.Optional[subprocess.Popen], timeout: int = 10): ...
+        async def aio(self, /, process: typing.Optional[subprocess.Popen], timeout: int = 10): ...
+
+    check_port_connection: __check_port_connection_spec[typing_extensions.Self]
 
     class ___start_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /): ...
@@ -24,6 +49,17 @@ class FlashManager:
 
     _start: ___start_spec[typing_extensions.Self]
 
+    class ___drain_container_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /):
+            """Background task that checks if we've encountered too many failures and drains the container if so."""
+            ...
+
+        async def aio(self, /):
+            """Background task that checks if we've encountered too many failures and drains the container if so."""
+            ...
+
+    _drain_container: ___drain_container_spec[typing_extensions.Self]
+
     class ___run_heartbeat_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, host: str, port: int): ...
         async def aio(self, /, host: str, port: int): ...
@@ -45,17 +81,27 @@ class FlashManager:
     close: __close_spec[typing_extensions.Self]
 
 class __flash_forward_spec(typing_extensions.Protocol):
-    def __call__(self, /, port: int, health_check_url: typing.Optional[str] = None) -> FlashManager:
+    def __call__(
+        self,
+        /,
+        port: int,
+        process: typing.Optional[subprocess.Popen] = None,
+        health_check_url: typing.Optional[str] = None,
+    ) -> FlashManager:
         """Forward a port to the Modal Flash service, exposing that port as a stable web endpoint.
-
         This is a highly experimental method that can break or be removed at any time without warning.
         Do not use this method unless explicitly instructed to do so by Modal support.
         """
         ...
 
-    async def aio(self, /, port: int, health_check_url: typing.Optional[str] = None) -> FlashManager:
+    async def aio(
+        self,
+        /,
+        port: int,
+        process: typing.Optional[subprocess.Popen] = None,
+        health_check_url: typing.Optional[str] = None,
+    ) -> FlashManager:
         """Forward a port to the Modal Flash service, exposing that port as a stable web endpoint.
-
         This is a highly experimental method that can break or be removed at any time without warning.
         Do not use this method unless explicitly instructed to do so by Modal support.
         """
@@ -85,8 +131,15 @@ class _FlashPrometheusAutoscaler:
 
     async def start(self): ...
     async def _run_autoscaler_loop(self): ...
-    async def _compute_target_containers(self, current_replicas: int) -> int: ...
+    async def _compute_target_containers_internal(self, current_replicas: int) -> int:
+        """Gets internal metrics from container to autoscale up or down."""
+        ...
+
+    async def _compute_target_containers_prometheus(self, current_replicas: int) -> int: ...
     async def _get_metrics(self, url: str) -> typing.Optional[dict[str, list[typing.Any]]]: ...
+    async def _get_container_metrics(
+        self, container_id: str
+    ) -> typing.Optional[modal_proto.api_pb2.TaskGetAutoscalingMetricsResponse]: ...
     async def _get_all_containers(self): ...
     def _make_scaling_decision(
         self,
@@ -147,11 +200,22 @@ class FlashPrometheusAutoscaler:
 
     _run_autoscaler_loop: ___run_autoscaler_loop_spec[typing_extensions.Self]
 
-    class ___compute_target_containers_spec(typing_extensions.Protocol[SUPERSELF]):
+    class ___compute_target_containers_internal_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /, current_replicas: int) -> int:
+            """Gets internal metrics from container to autoscale up or down."""
+            ...
+
+        async def aio(self, /, current_replicas: int) -> int:
+            """Gets internal metrics from container to autoscale up or down."""
+            ...
+
+    _compute_target_containers_internal: ___compute_target_containers_internal_spec[typing_extensions.Self]
+
+    class ___compute_target_containers_prometheus_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, current_replicas: int) -> int: ...
         async def aio(self, /, current_replicas: int) -> int: ...
 
-    _compute_target_containers: ___compute_target_containers_spec[typing_extensions.Self]
+    _compute_target_containers_prometheus: ___compute_target_containers_prometheus_spec[typing_extensions.Self]
 
     class ___get_metrics_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, url: str) -> typing.Optional[dict[str, list[typing.Any]]]: ...
@@ -159,6 +223,16 @@ class FlashPrometheusAutoscaler:
 
     _get_metrics: ___get_metrics_spec[typing_extensions.Self]
 
+    class ___get_container_metrics_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(
+            self, /, container_id: str
+        ) -> typing.Optional[modal_proto.api_pb2.TaskGetAutoscalingMetricsResponse]: ...
+        async def aio(
+            self, /, container_id: str
+        ) -> typing.Optional[modal_proto.api_pb2.TaskGetAutoscalingMetricsResponse]: ...
+
+    _get_container_metrics: ___get_container_metrics_spec[typing_extensions.Self]
+
     class ___get_all_containers_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /): ...
         async def aio(self, /): ...

modal/functions.pyi

@@ -85,6 +85,7 @@ class Function(
         proxy: typing.Optional[modal.proxy.Proxy] = None,
         retries: typing.Union[int, modal.retries.Retries, None] = None,
         timeout: int = 300,
+        startup_timeout: typing.Optional[int] = None,
         min_containers: typing.Optional[int] = None,
         max_containers: typing.Optional[int] = None,
         buffer_containers: typing.Optional[int] = None,
@@ -359,6 +360,17 @@ class Function(
 
     get_web_url: __get_web_url_spec[typing_extensions.Self]
 
+    class ___experimental_get_flash_urls_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /) -> typing.Optional[list[str]]:
+            """URL of the flash service for the function."""
+            ...
+
+        async def aio(self, /) -> typing.Optional[list[str]]:
+            """URL of the flash service for the function."""
+            ...
+
+    _experimental_get_flash_urls: ___experimental_get_flash_urls_spec[typing_extensions.Self]
+
     @property
     def is_generator(self) -> bool:
         """mdmd:hidden"""
@@ -433,7 +445,7 @@ class Function(
 
     _call_generator: ___call_generator_spec[typing_extensions.Self]
 
-    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
+    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
@@ -442,7 +454,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P, typing_extensions.Self]
+    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType, typing_extensions.Self]
 
     class __remote_gen_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -469,7 +481,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -493,7 +505,7 @@ class Function(
             ...
 
     _experimental_spawn: ___experimental_spawn_spec[
-        modal._functions.ReturnType, modal._functions.P, typing_extensions.Self
+        modal._functions.P, modal._functions.ReturnType, typing_extensions.Self
     ]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER, SUPERSELF]):
@@ -502,7 +514,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P, typing_extensions.Self]
 
-    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
+    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -523,7 +535,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P, typing_extensions.Self]
+    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType, typing_extensions.Self]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

modal/image.py

@@ -1863,12 +1863,18 @@ class _Image(_Object, type_prefix="im"):
     ) -> "_Image":
         """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
 
-        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
-        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+        You will need to pass a `modal.Secret` containing either IAM user credentials or OIDC
+        configuration to access the target ECR registry.
+
+        For IAM user authentication, set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`.
+
+        For OIDC authentication, set `AWS_ROLE_ARN` and `AWS_REGION`.
 
         IAM configuration details can be found in the AWS documentation for
         ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
 
+        For more details on using an AWS role to access ECR, see the [OIDC integration guide](https://modal.com/docs/guide/oidc-integration).
+
         See `Image.from_registry()` for information about the other parameters.
 
         **Example**

modal/image.pyi

@@ -720,12 +720,18 @@ class _Image(modal._object._Object):
     ) -> _Image:
         """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
 
-        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
-        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+        You will need to pass a `modal.Secret` containing either IAM user credentials or OIDC
+        configuration to access the target ECR registry.
+
+        For IAM user authentication, set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`.
+
+        For OIDC authentication, set `AWS_ROLE_ARN` and `AWS_REGION`.
 
         IAM configuration details can be found in the AWS documentation for
         ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
 
+        For more details on using an AWS role to access ECR, see the [OIDC integration guide](https://modal.com/docs/guide/oidc-integration).
+
         See `Image.from_registry()` for information about the other parameters.
 
         **Example**
@@ -1565,12 +1571,18 @@ class Image(modal.object.Object):
     ) -> Image:
         """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
 
-        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
-        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+        You will need to pass a `modal.Secret` containing either IAM user credentials or OIDC
+        configuration to access the target ECR registry.
+
+        For IAM user authentication, set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`.
+
+        For OIDC authentication, set `AWS_ROLE_ARN` and `AWS_REGION`.
 
         IAM configuration details can be found in the AWS documentation for
         ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
 
+        For more details on using an AWS role to access ECR, see the [OIDC integration guide](https://modal.com/docs/guide/oidc-integration).
+
         See `Image.from_registry()` for information about the other parameters.
 
         **Example**

modal/mount.py

@@ -866,6 +866,7 @@ async def _create_single_client_dependency_mount(
     uv_python_platform: str,
     check_if_exists: bool = True,
     allow_overwrite: bool = False,
+    dry_run: bool = False,
 ):
     import tempfile
 
@@ -930,17 +931,20 @@ async def _create_single_client_dependency_mount(
                 remote_path=REMOTE_SITECUSTOMIZE_PATH,
             )
 
-            try:
-                await python_mount._deploy.aio(
-                    mount_name,
-                    api_pb2.DEPLOYMENT_NAMESPACE_GLOBAL,
-                    environment_name=profile_environment,
-                    allow_overwrite=allow_overwrite,
-                    client=client,
-                )
-                print(f"✅ Deployed mount {mount_name} to global namespace.")
-            except GRPCError as e:
-                print(f"⚠️ Mount creation failed with {e.status}: {e.message}")
+            if not dry_run:
+                try:
+                    await python_mount._deploy.aio(
+                        mount_name,
+                        api_pb2.DEPLOYMENT_NAMESPACE_GLOBAL,
+                        environment_name=profile_environment,
+                        allow_overwrite=allow_overwrite,
+                        client=client,
+                    )
+                    print(f"✅ Deployed mount {mount_name} to global namespace.")
+                except GRPCError as e:
+                    print(f"⚠️ Mount creation failed with {e.status}: {e.message}")
+            else:
+                print(f"Dry run - skipping deployment of mount {mount_name}")
 
 
 async def _create_client_dependency_mounts(
@@ -948,6 +952,7 @@ async def _create_client_dependency_mounts(
     python_versions: list[str] = list(PYTHON_STANDALONE_VERSIONS),
     builder_versions: list[str] = ["2025.06"],  # Reenable "PREVIEW" during testing
     check_if_exists=True,
+    dry_run=False,
 ):
     arch = "x86_64"
     platform_tags = [
@@ -971,6 +976,7 @@ async def _create_client_dependency_mounts(
                         # in theory we may need to do at some point (hopefully not, but...)
                         check_if_exists=check_if_exists and builder_version != "PREVIEW",
                         allow_overwrite=builder_version == "PREVIEW",
+                        dry_run=dry_run,
                     )
                 )
     await TaskContext.gather(*coros)

modal/mount.pyi

@@ -568,12 +568,14 @@ async def _create_single_client_dependency_mount(
     uv_python_platform: str,
     check_if_exists: bool = True,
     allow_overwrite: bool = False,
+    dry_run: bool = False,
 ): ...
 async def _create_client_dependency_mounts(
     client=None,
     python_versions: list[str] = ["3.9", "3.10", "3.11", "3.12", "3.13"],
     builder_versions: list[str] = ["2025.06"],
     check_if_exists=True,
+    dry_run=False,
 ): ...
 
 class __create_client_dependency_mounts_spec(typing_extensions.Protocol):
@@ -584,6 +586,7 @@ class __create_client_dependency_mounts_spec(typing_extensions.Protocol):
         python_versions: list[str] = ["3.9", "3.10", "3.11", "3.12", "3.13"],
         builder_versions: list[str] = ["2025.06"],
         check_if_exists=True,
+        dry_run=False,
     ): ...
     async def aio(
         self,
@@ -592,6 +595,7 @@ class __create_client_dependency_mounts_spec(typing_extensions.Protocol):
         python_versions: list[str] = ["3.9", "3.10", "3.11", "3.12", "3.13"],
         builder_versions: list[str] = ["2025.06"],
         check_if_exists=True,
+        dry_run=False,
     ): ...
 
 create_client_dependency_mounts: __create_client_dependency_mounts_spec

modal/parallel_map.py

@@ -79,8 +79,10 @@ class _OutputValue:
 
 MAX_INPUTS_OUTSTANDING_DEFAULT = 1000
 
-# maximum number of inputs to send to the server in a single request
+# Maximum number of inputs to send to the server per FunctionPutInputs request
 MAP_INVOCATION_CHUNK_SIZE = 49
+SPAWN_MAP_INVOCATION_CHUNK_SIZE = 512
+
 
 if typing.TYPE_CHECKING:
     import modal.functions
@@ -159,6 +161,7 @@ class InputPumper:
         input_queue: asyncio.Queue,
         function: "modal.functions._Function",
         function_call_id: str,
+        max_batch_size: int,
         map_items_manager: Optional["_MapItemsManager"] = None,
     ):
         self.client = client
@@ -167,10 +170,11 @@ class InputPumper:
         self.input_queue = input_queue
         self.inputs_sent = 0
         self.function_call_id = function_call_id
+        self.max_batch_size = max_batch_size
 
     async def pump_inputs(self):
         assert self.client.stub
-        async for items in queue_batch_iterator(self.input_queue, max_batch_size=MAP_INVOCATION_CHUNK_SIZE):
+        async for items in queue_batch_iterator(self.input_queue, max_batch_size=self.max_batch_size):
             # Add items to the manager. Their state will be SENDING.
             if self.map_items_manager is not None:
                 await self.map_items_manager.add_items(items)
@@ -234,6 +238,7 @@ class SyncInputPumper(InputPumper):
             input_queue=input_queue,
             function=function,
             function_call_id=function_call_id,
+            max_batch_size=MAP_INVOCATION_CHUNK_SIZE,
             map_items_manager=map_items_manager,
         )
         self.retry_queue = retry_queue
@@ -241,7 +246,7 @@ class SyncInputPumper(InputPumper):
         self.function_call_jwt = function_call_jwt
 
     async def retry_inputs(self):
-        async for retriable_idxs in queue_batch_iterator(self.retry_queue, max_batch_size=MAP_INVOCATION_CHUNK_SIZE):
+        async for retriable_idxs in queue_batch_iterator(self.retry_queue, max_batch_size=self.max_batch_size):
             # For each index, use the context in the manager to create a FunctionRetryInputsItem.
             # This will also update the context state to RETRYING.
             inputs: list[api_pb2.FunctionRetryInputsItem] = await self.map_items_manager.prepare_items_for_retry(
@@ -269,7 +274,13 @@ class AsyncInputPumper(InputPumper):
         function: "modal.functions._Function",
         function_call_id: str,
     ):
-        super().__init__(client, input_queue=input_queue, function=function, function_call_id=function_call_id)
+        super().__init__(
+            client,
+            input_queue=input_queue,
+            function=function,
+            function_call_id=function_call_id,
+            max_batch_size=SPAWN_MAP_INVOCATION_CHUNK_SIZE,
+        )
 
     async def pump_inputs(self):
         async for _ in super().pump_inputs():
@@ -762,7 +773,12 @@ async def _map_invocation_inputplane(
             metadata = await client.get_input_plane_metadata(function._input_plane_region)
 
             response: api_pb2.MapStartOrContinueResponse = await retry_transient_errors(
-                input_plane_stub.MapStartOrContinue, request, metadata=metadata
+                input_plane_stub.MapStartOrContinue,
+                request,
+                metadata=metadata,
+                additional_status_codes=[Status.RESOURCE_EXHAUSTED],
+                max_delay=PUMP_INPUTS_MAX_RETRY_DELAY,
+                max_retries=None,
             )
 
             # match response items to the corresponding request item index
@@ -794,7 +810,11 @@ async def _map_invocation_inputplane(
                     await function_call_id_received.wait()
                     continue
 
-                await asyncio.sleep(1)
+                sleep_task = asyncio.create_task(asyncio.sleep(1))
+                map_done_task = asyncio.create_task(map_done_event.wait())
+                done, _ = await asyncio.wait([sleep_task, map_done_task], return_when=FIRST_COMPLETED)
+                if map_done_task in done:
+                    break
 
                 # check_inputs = [(idx, attempt_token), ...]
                 check_inputs = map_items_manager.get_input_idxs_waiting_for_output()

modal/parallel_map.pyi

@@ -89,6 +89,7 @@ class InputPumper:
         input_queue: asyncio.queues.Queue,
         function: modal._functions._Function,
         function_call_id: str,
+        max_batch_size: int,
         map_items_manager: typing.Optional[_MapItemsManager] = None,
     ):
         """Initialize self.  See help(type(self)) for accurate signature."""

modal/sandbox.py

@@ -24,6 +24,7 @@ from ._utils.async_utils import TaskContext, synchronize_api
 from ._utils.deprecation import deprecation_warning
 from ._utils.grpc_utils import retry_transient_errors
 from ._utils.mount_utils import validate_network_file_systems, validate_volumes
+from ._utils.name_utils import is_valid_object_name
 from .client import _Client
 from .config import config
 from .container_process import _ContainerProcess
@@ -73,6 +74,16 @@ def _validate_exec_args(args: Sequence[str]) -> None:
         )
 
 
+def _warn_if_invalid_name(name: str) -> None:
+    if not is_valid_object_name(name):
+        deprecation_warning(
+            (2025, 9, 3),
+            f"Sandbox name '{name}' will be considered invalid in a future release."
+            "\n\nNames may contain only alphanumeric characters, dashes, periods, and underscores,"
+            " must be shorter than 64 characters, and cannot conflict with App ID strings.",
+        )
+
+
 class DefaultSandboxNameOverride(str):
     """A singleton class that represents the default sandbox name override.
 
@@ -109,6 +120,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         secrets: Sequence[_Secret],
         name: Optional[str] = None,
         timeout: int = 300,
+        idle_timeout: Optional[int] = None,
         workdir: Optional[str] = None,
         gpu: GPU_T = None,
         cloud: Optional[str] = None,
@@ -213,6 +225,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 mount_ids=[mount.object_id for mount in mounts] + [mount.object_id for mount in image._mount_layers],
                 secret_ids=[secret.object_id for secret in secrets],
                 timeout_secs=timeout,
+                idle_timeout_secs=idle_timeout,
                 workdir=workdir,
                 resources=convert_fn_config_to_resources_config(
                     cpu=cpu, memory=memory, gpu=gpu, ephemeral_disk=ephemeral_disk
@@ -257,7 +270,9 @@ class _Sandbox(_Object, type_prefix="sb"):
         image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
         secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
         network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
-        timeout: int = 300,  # Maximum execution time of the sandbox in seconds.
+        timeout: int = 300,  # Maximum lifetime of the sandbox in seconds.
+        # The amount of time in seconds that a sandbox can be idle before being terminated.
+        idle_timeout: Optional[int] = None,
         workdir: Optional[str] = None,  # Working directory of the sandbox.
         gpu: GPU_T = None,
         cloud: Optional[str] = None,
@@ -312,7 +327,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         if environment_name is not None:
             deprecation_warning(
                 (2025, 7, 16),
-                "Passing `environment_name` to `Sandbox.create` is deprecated and will be removed in a future release.",
+                "Passing `environment_name` to `Sandbox.create` is deprecated and will be removed in a future release. "
                 "A sandbox's environment is determined by the app it is associated with.",
             )
 
@@ -324,6 +339,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             secrets=secrets,
             network_file_systems=network_file_systems,
             timeout=timeout,
+            idle_timeout=idle_timeout,
             workdir=workdir,
             gpu=gpu,
             cloud=cloud,
@@ -355,7 +371,9 @@ class _Sandbox(_Object, type_prefix="sb"):
         secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
         mounts: Sequence[_Mount] = (),
         network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
-        timeout: int = 300,  # Maximum execution time of the sandbox in seconds.
+        timeout: int = 300,  # Maximum lifetime of the sandbox in seconds.
+        # The amount of time in seconds that a sandbox can be idle before being terminated.
+        idle_timeout: Optional[int] = None,
         workdir: Optional[str] = None,  # Working directory of the sandbox.
         gpu: GPU_T = None,
         cloud: Optional[str] = None,
@@ -397,6 +415,11 @@ class _Sandbox(_Object, type_prefix="sb"):
         from .app import _App
 
         _validate_exec_args(args)
+        if name is not None:
+            _warn_if_invalid_name(name)
+
+        if block_network and (encrypted_ports or h2_ports or unencrypted_ports):
+            raise InvalidError("Cannot specify open ports when `block_network` is enabled")
 
         # TODO(erikbern): Get rid of the `_new` method and create an already-hydrated object
         obj = _Sandbox._new(
@@ -405,6 +428,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             secrets=secrets,
             name=name,
             timeout=timeout,
+            idle_timeout=idle_timeout,
             workdir=workdir,
             gpu=gpu,
             cloud=cloud,
@@ -479,7 +503,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         environment_name: Optional[str] = None,
         client: Optional[_Client] = None,
     ) -> "_Sandbox":
-        """Get a running Sandbox by name from the given app.
+        """Get a running Sandbox by name from a deployed App.
 
         Raises a modal.exception.NotFoundError if no running sandbox is found with the given name.
         A Sandbox's name is the `name` argument passed to `Sandbox.create`.
@@ -776,6 +800,9 @@ class _Sandbox(_Object, type_prefix="sb"):
     ):
         client = client or await _Client.from_env()
 
+        if name is not None and name != _DEFAULT_SANDBOX_NAME_OVERRIDE:
+            _warn_if_invalid_name(name)
+
         if name is _DEFAULT_SANDBOX_NAME_OVERRIDE:
             restore_req = api_pb2.SandboxRestoreRequest(
                 snapshot_id=snapshot.object_id,