modal 1.6.2.dev2__py3-none-any.whl → 1.6.2.dev4__py3-none-any.whl

modal/_environments.py

@@ -54,7 +54,7 @@ class _EnvironmentManager:
         modal.Environment.objects.create("my-environment")
         ```
         """
-        check_environment_name(name)
+        check_environment_name(name, allow_periods=False)
 
         client = await _Client.from_env() if client is None else client
         request = api_pb2.EnvironmentCreateRequest(name=name, is_managed=restricted)
@@ -464,7 +464,7 @@ class _Environment(_Object, type_prefix="en"):
         client: _Client | None = None,
     ) -> "_Environment":
         """Look up an Environment object using its name."""
-        check_environment_name(name)
+        check_environment_name(name, allow_periods=True)
         return _Environment._get_or_create(
             name=name,
             repr=f"Environment.from_name({name!r})",

modal/_functions.py

@@ -819,8 +819,8 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             raise InvalidError(
                 f"`min_containers` ({min_containers}) cannot be greater than `max_containers` ({max_containers})"
             )
-        if scaledown_window is not None and scaledown_window <= 0:
-            raise InvalidError("`scaledown_window` must be > 0")
+        if scaledown_window is not None and not (2 <= scaledown_window <= 3600):
+            raise InvalidError("`scaledown_window` must be between 2 and 3600 (inclusive)")
 
         autoscaler_settings = api_pb2.AutoscalerSettings(
             min_containers=min_containers,

modal/_utils/name_utils.py

@@ -27,13 +27,15 @@ def is_valid_object_name(name: str) -> bool:
     )
 
 
-def is_valid_environment_name(name: str) -> bool:
+def is_valid_environment_name(name: str, *, allow_periods: bool) -> bool:
     # first char is alnum, the rest allows other chars
     # The "en-" prefix is reserved for environment IDs, so that references
     # to environments can be resolved by either name or ID unambiguously.
+    # New names cannot contain periods, but some existing Environments have them and must stay resolvable.
+    rest_chars = r"a-zA-Z0-9-_." if allow_periods else r"a-zA-Z0-9-_"
     return (
         len(name) <= 64
-        and re.match(r"^[a-zA-Z0-9][a-zA-Z0-9-_.]+$", name) is not None
+        and re.match(rf"^[a-zA-Z0-9][{rest_chars}]*$", name) is not None
         and not name.lower().startswith("en-")
     )
 
@@ -67,12 +69,12 @@ def check_object_name(name: str, object_type: str) -> None:
         raise InvalidError(message)
 
 
-def check_environment_name(name: str) -> None:
+def check_environment_name(name: str, *, allow_periods: bool) -> None:
     message = (
         f"Invalid Environment name: '{name}'."
-        "\n\nEnvironment names can only start with alphanumeric characters,"
-        " may contain only alphanumeric characters, dashes, periods, and underscores,"
-        " must be shorter than 64 characters, and cannot start with 'en-'."
+        "\n\nEnvironment names must be 1-64 characters, can only start with alphanumeric characters,"
+        " may contain only alphanumeric characters, dashes, and underscores,"
+        " and cannot start with 'en-'."
     )
-    if not is_valid_environment_name(name):
+    if not is_valid_environment_name(name, allow_periods=allow_periods):
         raise InvalidError(message)

modal/cli/container.py

@@ -27,7 +27,8 @@ from modal.cli.utils import (
 )
 from modal.client import _Client
 from modal.exception import ConflictError, InvalidError
-from modal.sandbox import SandboxVersion, _container_exec, _get_sandbox_version, _Sandbox
+from modal.sandbox._sandbox import SandboxVersion, _get_sandbox_version, _Sandbox
+from modal.sandbox.sandbox import _container_exec
 from modal_proto import api_pb2
 
 from ._help import ModalGroup

modal/cli/endpoint.py

@@ -260,7 +260,7 @@ async def list_(*, json: bool = False, env: Optional[str] = None):
 @click.option(
     "--name",
     default=None,
-    help="Endpoint name. If not provided, a default will be derived from the model name.",
+    help="Endpoint name. Defaults to inference-{number} if not provided.",
 )
 @click.option(
     "--model",
@@ -410,6 +410,8 @@ async def create(
 
     output = OutputManager.get()
     output.print(f"[green]✓[/green] Endpoint '{resp.name}' ({resp.endpoint_id}) was created and started provisioning.")
+    if resp.model_name:
+        output.print(f'  → Send [cyan]"model": "{resp.model_name}"[/cyan] in requests to the Endpoint.')
     if resp.endpoint_page_url:
         output.print(f"  → View progress at [magenta]{resp.endpoint_page_url}[/magenta].")
         output.print("  → The Endpoint will also appear in [cyan]modal endpoint list[/cyan].")
@@ -517,6 +519,7 @@ async def info(
                 {
                     "name": endpoint_info.name,
                     "endpoint_id": endpoint_id,
+                    "model_name": endpoint_info.model_name or None,
                     "repo_id": endpoint_info.repo_id,
                     "revision": endpoint_info.revision or None,
                     "volume_id": endpoint_info.volume_id or None,
@@ -547,6 +550,8 @@ async def info(
     header.add_row(Text("Endpoint:"), endpoint_text)
     header.add_row(Text("Endpoint ID:"), Text(endpoint_id))
     header.add_row(Text("State:"), Text(status))
+    if endpoint_info.model_name:
+        header.add_row(Text("Model name:"), Text(endpoint_info.model_name))
     model_text = Text(endpoint_info.repo_id)
     if endpoint_info.revision:
         model_text.append(f"@{endpoint_info.revision[:7]}")

modal/cli/environment.py

@@ -87,7 +87,7 @@ def create(
     default_role: str | None = None,
     public: bool = False,
 ):
-    check_environment_name(name)
+    check_environment_name(name, allow_periods=False)
     Environment.objects.create(
         name,
         restricted=restricted,
@@ -116,8 +116,8 @@ def update(
     if set_name is None and set_web_suffix is None:
         raise UsageError("You need to at least one new property (using --set-name or --set-web-suffix)")
 
-    if set_name:
-        check_environment_name(set_name)
+    if set_name and set_name != current_name:
+        check_environment_name(set_name, allow_periods=False)
 
     environments.update_environment(current_name, new_name=set_name, new_web_suffix=set_web_suffix)
     rich.print("[green]✓[/green] Environment updated")

modal/cli/shell.py

@@ -17,7 +17,9 @@ from ..functions import Function
 from ..image import Image
 from ..mount import _Mount
 from ..runner import interactive_shell
-from ..sandbox import _MAIN_CONTAINER_NAME, Sandbox, SandboxVersion, _container_exec, _get_sandbox_version
+from ..sandbox import Sandbox
+from ..sandbox._sandbox import _MAIN_CONTAINER_NAME, SandboxVersion, _get_sandbox_version
+from ..sandbox.sandbox import _container_exec
 from ..secret import Secret
 from ..stream_type import StreamType
 from ..types import SandboxRuntime

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.2.dev2",
+        version: str = "1.6.2.dev4",
         *,
         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.2.dev2",
+        version: str = "1.6.2.dev4",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):

modal/experimental/__init__.py

@@ -93,6 +93,72 @@ def clustered(size: int, broadcast: bool = True, rdma: bool = False, fabric_size
     return wrapper
 
 
+@dataclass
+class ClusterReservationTask:
+    """A container running on a worker that belongs to a cluster reservation."""
+
+    task_id: str
+    cluster_rank: int
+    app_id: str
+    function_id: str
+
+
+@dataclass
+class ClusterReservation:
+    """Current state of reserved multi-node cluster capacity in a Workspace."""
+
+    name: str  # Reservation name, as configured by Modal
+    gpu_type: str  # e.g. "B300"
+    region: str
+    min_reserved_workers: int  # Number of workers Modal has committed to keep reserved
+    reserved_workers: int  # Healthy reserved workers currently present (active + idle)
+    active_workers: int  # Reserved workers running this Workspace's containers
+    idle_workers: int  # Reserved workers available for new clusters
+    unfulfilled_workers: int  # max(0, min_reserved_workers - reserved_workers)
+    tasks: list[ClusterReservationTask]  # Containers on reserved workers, ordered by cluster then rank
+
+
+@synchronizer.create_blocking
+async def list_cluster_reservations(*, client: _Client | None = None) -> list[ClusterReservation]:
+    """List reserved multi-node cluster capacity for the current Workspace.
+
+    Returns one entry per reservation Modal has configured for the Workspace, with how many of the
+    reserved workers are currently present, in use, idle or missing. Only Workspaces with reserved
+    cluster capacity (or explicitly allowlisted by Modal) may call this; others get a
+    `modal.exception.PermissionDeniedError`.
+
+    This interface is experimental. This information will continue to be available in the future,
+    but it may be accessed via a different interface, and the return value may have a different shape.
+    """
+    client = client or await _Client.from_env()
+
+    resp: api_pb2.ClusterReservationListResponse = await client._stub.ClusterReservationList(
+        api_pb2.ClusterReservationListRequest()
+    )
+    return [
+        ClusterReservation(
+            name=reservation.name,
+            gpu_type=reservation.gpu_type,
+            region=reservation.region,
+            min_reserved_workers=reservation.min_reserved_workers,
+            reserved_workers=reservation.reserved_workers,
+            active_workers=reservation.active_workers,
+            idle_workers=reservation.idle_workers,
+            unfulfilled_workers=reservation.unfulfilled_workers,
+            tasks=[
+                ClusterReservationTask(
+                    task_id=task.task_id,
+                    cluster_rank=task.cluster_rank,
+                    app_id=task.app_id,
+                    function_id=task.function_id,
+                )
+                for task in reservation.tasks
+            ],
+        )
+        for reservation in resp.reservations
+    ]
+
+
 @dataclass
 class AppInfo:
     app_id: str

modal/runner.py

@@ -43,7 +43,7 @@ from .exception import (
 )
 from .output import OutputManager
 from .running_app import RunningApp, running_app_from_layout
-from .sandbox import _Sandbox
+from .sandbox._sandbox import _Sandbox
 from .secret import _Secret
 from .stream_type import StreamType
 

modal/sandbox/__init__.py

@@ -0,0 +1,9 @@
+# Copyright Modal Labs 2026
+from ._sandbox import (
+    Probe as Probe,
+)
+from .sandbox import (
+    Sandbox as Sandbox,
+    SidecarContainer as SidecarContainer,
+    SidecarManager as SidecarManager,
+)

modal/{sandbox.py → sandbox/_sandbox.py}

@@ -23,31 +23,31 @@ from modal._supports_logs import LogsFilters, _LogQueryData
 from modal._tunnel import Tunnel
 from modal.cloud_bucket_mount import _CloudBucketMount, cloud_bucket_mounts_to_proto
 from modal.mount import _Mount
-from modal.secret import _local_secret_env, _resolvable_secrets
+from modal.secret import _local_secret_env, _resolvable_secrets, _secret_sources
 from modal.volume import _Volume, _volume_to_mount_proto
 from modal_proto import api_pb2, task_command_router_pb2 as sr_pb2
 
-from ._image import _Image
-from ._load_context import LoadContext
-from ._object import _get_environment_name, _Object
-from ._outbound_policy import _OutboundPolicy, _validate_compatible_network_access
-from ._output.pty import get_pty_info
-from ._resolver import Resolver
-from ._resources import convert_fn_config_to_resources_config
-from ._utils.async_utils import TaskContext, synchronize_api, synchronizer
-from ._utils.deprecation import deprecation_warning
-from ._utils.grpc_utils import Retry, RetryTimeoutError
-from ._utils.mount_utils import (
+from .._image import _Image
+from .._load_context import LoadContext
+from .._object import _get_environment_name, _Object
+from .._outbound_policy import _OutboundPolicy, _validate_compatible_network_access
+from .._output.pty import get_pty_info
+from .._resolver import Resolver
+from .._resources import convert_fn_config_to_resources_config
+from .._utils.async_utils import TaskContext
+from .._utils.deprecation import deprecation_warning
+from .._utils.grpc_utils import Retry, RetryTimeoutError
+from .._utils.mount_utils import (
     validate_network_file_systems,
     validate_volumes,
     validate_volumes_by_object_id,
 )
-from ._utils.name_utils import check_object_name
-from ._utils.task_command_router_client import TaskCommandRouterClient, _is_v2_task_id
-from .client import _Client
-from .config import config, logger
-from .container_process import _ContainerProcess
-from .exception import (
+from .._utils.name_utils import check_object_name
+from .._utils.task_command_router_client import TaskCommandRouterClient, _is_v2_task_id
+from ..client import _Client
+from ..config import config, logger
+from ..container_process import _ContainerProcess
+from ..exception import (
     ClientClosed,
     ConflictError,
     ExecutionError,
@@ -61,7 +61,7 @@ from .exception import (
     SnapshotCreationError,
     TimeoutError,
 )
-from .io_streams import (
+from ..io_streams import (
     StreamReader,
     StreamWriter,
     _StreamReader,
@@ -71,13 +71,13 @@ from .io_streams import (
     _StreamWriterThroughCommandRouterSandboxParams,
     _StreamWriterThroughServerParams,
 )
-from .network_file_system import _NetworkFileSystem, network_file_system_mount_protos
-from .proxy import _Proxy
-from .sandbox_fs import _SandboxFilesystem
-from .secret import _Secret
-from .snapshot import _SandboxSnapshot
-from .stream_type import StreamType
-from .types import SandboxConnectCredentials, SandboxRuntime
+from ..network_file_system import _NetworkFileSystem, network_file_system_mount_protos
+from ..proxy import _Proxy
+from ..sandbox_fs import _SandboxFilesystem
+from ..secret import _Secret
+from ..snapshot import _SandboxSnapshot
+from ..stream_type import StreamType
+from ..types import SandboxConnectCredentials, SandboxRuntime
 
 _default_image: _Image = _Image.debian_slim()
 _EXIT_SNAPSHOT_NOT_FOUND_ERROR_CODES = frozenset(
@@ -307,11 +307,11 @@ class DefaultSandboxNameOverride(str):
     """
 
     def __repr__(self) -> str:
-        # NOTE: this must match the instance var name below in order for type stubs to work 😬
-        return "_DEFAULT_SANDBOX_NAME_OVERRIDE"
+        # NOTE: this must match the qualified instance var name below in order for type stubs to work 😬
+        return "modal.sandbox._sandbox._DEFAULT_SANDBOX_NAME_OVERRIDE"
 
 
-_DEFAULT_SANDBOX_NAME_OVERRIDE = DefaultSandboxNameOverride()
+_DEFAULT_SANDBOX_NAME_OVERRIDE: DefaultSandboxNameOverride = DefaultSandboxNameOverride()
 
 
 @dataclass(frozen=True)
@@ -386,7 +386,7 @@ def _resolve_app_id_and_client(
     client: "_Client | None",
 ) -> "tuple[str | None, _Client | None]":
     """Resolve the App id and client for Sandbox creation, validating that an App is available."""
-    from .app import _App
+    from ..app import _App
 
     if app is not None:
         if app.app_id is None:
@@ -1116,9 +1116,6 @@ class _Sandbox(_Object, type_prefix="sb"):
                 dep_tasks.append(resolver.load(proxy, load_context))
             dep_timings = await _gather_load_with_timings(dep_tasks) if dep_tasks else []
 
-            # `env` takes precedence over environment variables from secrets
-            env_dict = _local_secret_env(secrets) | ephemeral_env
-
             validate_volumes_by_object_id(validated_volumes)
 
             volume_mounts = [_volume_to_mount_proto(path, volume) for path, volume in validated_volumes]
@@ -1165,7 +1162,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             create_req = api_pb2.SandboxCreateV2Request(
                 app_id=load_context.app_id,
                 definition=definition,
-                ephemeral_secrets=api_pb2.StringMap(contents=env_dict) if env_dict else None,
+                secret_sources=_secret_sources(secrets, ephemeral_env),
                 tags=tag_protos,
                 cloud_bucket_mount_credentials=cloud_bucket_credientials,
             )
@@ -2306,8 +2303,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         secret_coros = [secret.hydrate(client=self._client) for secret in resolvable_secrets]
         await TaskContext.gather(*secret_coros)
 
-        env_dict = _local_secret_env(secrets)
-        env_dict |= {k: v for k, v in (env or {}).items() if v is not None}
+        env_dict = {k: v for k, v in (env or {}).items() if v is not None}
 
         task_id = await self._get_task_id(raise_if_task_complete=True)
 
@@ -2324,8 +2320,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             stderr=stderr,
             timeout=timeout,
             workdir=workdir,
-            secret_ids=[secret.object_id for secret in resolvable_secrets],
-            env=env_dict,
+            secret_sources=_secret_sources(secrets, env_dict),
             text=text,
             bufsize=bufsize,
             runtime_debug=config.get("function_runtime_debug"),
@@ -2342,8 +2337,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         stderr: StreamType = StreamType.PIPE,
         timeout: int | None = None,
         workdir: str | None = None,
-        secret_ids: Collection[str] | None = None,
-        env: dict[str, str] | None = None,
+        secret_sources: Collection[api_pb2.SecretSource] | None = None,
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
         runtime_debug: bool = False,
@@ -2382,11 +2376,10 @@ class _Sandbox(_Object, type_prefix="sb"):
             stderr_config=stderr_config,
             timeout_secs=timeout,
             workdir=workdir,
-            secret_ids=secret_ids,
+            secret_sources=secret_sources,
             pty_info=pty_info,
             runtime_debug=runtime_debug,
             container_id=container_id or "",
-            env=env or {},
         )
         _ = await command_router_client.exec_start(start_req)
 
@@ -3233,8 +3226,7 @@ class _SidecarManager:
                 *(resolver.load(dependency, load_context) for dependency in dependencies if not dependency._is_hydrated)
             )
 
-        # `env` takes precedence over environment variables from secrets
-        env_dict = _local_secret_env(secrets) | (env or {})
+        secret_sources = _secret_sources(secrets, env)
 
         # Validate that the same volume (by object_id) isn't mounted at multiple paths. This relies on
         # the volumes being hydrated above, since it compares object_ids.
@@ -3271,7 +3263,7 @@ class _SidecarManager:
                 sandbox_id=self._sandbox.object_id,
                 container_name=name,
                 definition=definition,
-                ephemeral_secrets=api_pb2.StringMap(contents=env_dict) if env_dict else None,
+                secret_sources=secret_sources,
                 cloud_bucket_mount_credentials=cloud_bucket_credentials,
             )
             client = self._sandbox._client
@@ -3286,9 +3278,8 @@ class _SidecarManager:
                     container_name=name,
                     image_id=image.object_id,
                     args=list(args),
-                    env=env_dict,
                     workdir=workdir or "",
-                    secret_ids=[secret.object_id for secret in resolvable_secrets],
+                    secret_sources=secret_sources,
                     volume_mounts=volume_mounts,
                     network_access=network_access,
                     pty_info=pty_info,
@@ -3328,7 +3319,6 @@ class _SidecarManager:
         ]
 
 
-@synchronizer.create_blocking
 async def _container_exec(
     pty: bool,
     container_id: str = "",
@@ -3386,8 +3376,3 @@ async def _container_exec(
             stdout=StreamType.STDOUT,
             stderr=StreamType.STDOUT,
         ).wait()
-
-
-SidecarContainer = synchronize_api(_SidecarContainer)
-SidecarManager = synchronize_api(_SidecarManager)
-Sandbox = synchronize_api(_Sandbox)

modal/sandbox/sandbox.py

@@ -0,0 +1,9 @@
+# Copyright Modal Labs 2026
+from .._utils.async_utils import synchronize_api, synchronizer
+from . import _sandbox
+
+SidecarContainer = synchronize_api(_sandbox._SidecarContainer, target_module=__name__)
+SidecarManager = synchronize_api(_sandbox._SidecarManager, target_module=__name__)
+Sandbox = synchronize_api(_sandbox._Sandbox, target_module=__name__)
+
+_container_exec = synchronizer.create_blocking(_sandbox._container_exec, "_container_exec", target_module=__name__)