modAL 1.4.0__tar.gz → 1.4.1__tar.gz

{modal-1.4.0 → modal-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.4.0
+Version: 1.4.1
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0
@@ -23,7 +23,7 @@ Requires-Dist: grpclib<0.4.10,>=0.4.7; python_version < "3.14"
 Requires-Dist: grpclib<0.4.10,>=0.4.9; python_version >= "3.14"
 Requires-Dist: protobuf!=4.24.0,<7.0,>=3.19
 Requires-Dist: rich>=12.0.0
-Requires-Dist: synchronicity~=0.11.1
+Requires-Dist: synchronicity~=0.12.1
 Requires-Dist: toml
 Requires-Dist: typer>=0.9
 Requires-Dist: types-certifi

{modal-1.4.0 → modal-1.4.1}/modal/__init__.py

@@ -38,7 +38,7 @@ try:
     from .proxy import Proxy
     from .queue import Queue
     from .retries import Retries
-    from .sandbox import Sandbox
+    from .sandbox import Probe, Sandbox
     from .schedule import Cron, Period
     from .scheduler_placement import SchedulerPlacement
     from .secret import Secret
@@ -68,6 +68,7 @@ __all__ = [
     "Image",
     "NetworkFileSystem",
     "Period",
+    "Probe",
     "Proxy",
     "Queue",
     "Retries",

{modal-1.4.0 → modal-1.4.1}/modal/_utils/sandbox_fs_utils.py

@@ -28,6 +28,7 @@ _EXEC_SANDBOX_UNAVAILABLE_ERROR_TYPES = (NotFoundError, ServiceError, Connection
 class ErrorPayload:
     error_kind: str
     message: str
+    detail: str = ""
 
 
 def _stderr_to_text(stderr: Union[str, bytes]) -> str:
@@ -51,11 +52,18 @@ def try_parse_error_payload(stderr: Union[str, bytes]) -> Optional[ErrorPayload]
         return None
     if not isinstance(message, str) or not message.strip():
         return None
-    return ErrorPayload(error_kind=error_kind, message=message)
+    detail = payload.get("detail", "")
+    if not isinstance(detail, str):
+        detail = ""
+    return ErrorPayload(error_kind=error_kind, message=message, detail=detail)
 
 
 def raise_read_file_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
     if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools read error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
         if payload.error_kind == "NotFound":
             raise SandboxFilesystemNotFoundError(f"{payload.message}: {remote_path}")
         if payload.error_kind == "IsDirectory":
@@ -106,6 +114,10 @@ def translate_exec_unexpected_error(operation: str, path: str, exc: Exception) -
 
 def raise_write_file_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
     if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools write error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
         if payload.error_kind == "NotDirectory" or payload.error_kind == "AlreadyExists":
             raise SandboxFilesystemNotADirectoryError(f"{payload.message}: {remote_path}")
         if payload.error_kind == "IsDirectory":

{modal-1.4.0 → modal-1.4.1}/modal/_utils/task_command_router_client.py

@@ -2,6 +2,7 @@
 import asyncio
 import base64
 import json
+import socket
 import ssl
 import time
 import urllib.parse
@@ -181,7 +182,10 @@ class TaskCommandRouterClient:
             closed_error_message="Unable to perform operation on a detached sandbox",
         )
 
-        await _connect_channel(channel)
+        try:
+            await _connect_channel(channel)
+        except socket.gaierror as exc:
+            raise ConnectionError(f"Could not resolve hostname '{host}': {exc}") from exc
         loop = asyncio.get_running_loop()
         jwt_refresh_lock = asyncio.Lock()
 

{modal-1.4.0 → modal-1.4.1}/modal/cli/container.py

@@ -1,4 +1,5 @@
 # Copyright Modal Labs 2022
+import warnings
 from datetime import datetime, timezone
 from typing import Optional, Union
 
@@ -185,20 +186,40 @@ async def logs(
         task_info_resp = await client.stub.TaskGetInfo(api_pb2.TaskGetInfoRequest(task_id=task_id))
         app_id = task_info_resp.app_id
 
+        if not task_info_resp.info.started_at:
+            # Unlikely race or Modal backend issue, don't treat as a usage exception
+            return
+        container_started_dt = datetime.fromtimestamp(task_info_resp.info.started_at, timezone.utc)
+
         now = datetime.now(timezone.utc)
         if all_logs:
-            since_dt = datetime.fromtimestamp(task_info_resp.info.started_at, timezone.utc)
+            since_dt = container_started_dt
             if task_info_resp.info.finished_at:
                 until_dt = datetime.fromtimestamp(task_info_resp.info.finished_at, timezone.utc)
             else:
                 until_dt = now
         else:
-            since_dt = _parse_time_arg(since, default=now) if since else None
-            until_dt = _parse_time_arg(until, default=now) if until else None
+            since_dt = _parse_time_arg(since, default=container_started_dt)
+            if task_info_resp.info.finished_at:
+                default_until_dt = datetime.fromtimestamp(task_info_resp.info.finished_at, timezone.utc)
+            else:
+                default_until_dt = now
+            until_dt = _parse_time_arg(until, default=default_until_dt)
 
-        if since_dt is not None and until_dt is not None and since_dt >= until_dt:
+        if since is not None and until is not None and since_dt >= until_dt:
+            # User provided both --since and --until, but did so incorrectly
             raise UsageError("--since must be before --until.")
 
+        if since is not None and until is None and since_dt >= until_dt:
+            # User provided only --since and it is after the container finished
+            warnings.warn("--since time is after the Container finished, no logs to fetch.", UserWarning)
+            return
+
+        if until is not None and since is None and since_dt >= until_dt:
+            # User provided only --until and it is before the Container started
+            warnings.warn("--until time is before the Container started, no logs to fetch.", UserWarning)
+            return
+
         if since_dt is not None:
             effective_until = until_dt or now
             if effective_until - since_dt > _MAX_FETCH_RANGE:

{modal-1.4.0 → modal-1.4.1}/modal/cli/import_refs.py

@@ -127,6 +127,7 @@ class AutoRunPriority:
 
 def list_cli_commands(
     module_members: dict[str, typing.Any],
+    include_service_functions: bool = False,
 ) -> list[CLICommand]:
     """
     Extracts all runnables found either directly in the input module, or in any of the Apps listed in that module
@@ -149,8 +150,8 @@ def list_cli_commands(
             all_runnables[local_entrypoint].append(f"{app_name}.{name}")
             priorities[local_entrypoint] = AutoRunPriority.APP_LOCAL_ENTRYPOINT
         for name, function in app.registered_functions.items():
-            if function.info.is_service_class():
-                continue  # Skip class and server service functions since they don't have associated cli commands
+            if function.info.is_service_class() and not include_service_functions:
+                continue  # Skip class and server service functions for all commands except `modal shell`.
             all_runnables[function].append(f"{app_name}.{name}")
             priorities[function] = AutoRunPriority.APP_FUNCTION
         for cls_name, cls in app.registered_classes.items():
@@ -322,7 +323,12 @@ def _get_runnable_app(runnable: Runnable) -> App:
 
 
 def import_and_filter(
-    import_ref: ImportRef, *, base_cmd: str, accept_local_entrypoint=True, accept_webhook=False
+    import_ref: ImportRef,
+    *,
+    base_cmd: str,
+    accept_local_entrypoint=True,
+    accept_webhook=False,
+    accept_service_functions=False,
 ) -> tuple[Optional[Runnable], list[CLICommand]]:
     """Takes a function ref string and returns a single determined "runnable" to use, and a list of all available
     runnables.
@@ -339,7 +345,10 @@ def import_and_filter(
     """
     # all commands:
     module = import_file_or_module(import_ref, base_cmd)
-    cli_commands = list_cli_commands(dict(inspect.getmembers(module)))
+    cli_commands = list_cli_commands(
+        dict(inspect.getmembers(module)),
+        include_service_functions=accept_service_functions,
+    )
 
     # all commands that satisfy local entrypoint/accept webhook limitations AND object path prefix
 

{modal-1.4.0 → modal-1.4.1}/modal/cli/run.py

@@ -7,7 +7,7 @@ import sys
 import time
 import typing
 from dataclasses import dataclass
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, get_args
 
 import click
 import typer
@@ -504,7 +504,9 @@ def deploy(
         False, "-m", help="Interpret argument as a Python module path instead of a file/script path"
     ),
     timestamps: bool = typer.Option(False, "--timestamps", help="Show timestamps for each log line."),
-    strategy: DEPLOYMENT_STRATEGY_TYPE = typer.Option("rolling", help="Deployment strategy"),
+    strategy: str = typer.Option(
+        "rolling", help="Deployment strategy", click_type=click.Choice(get_args(DEPLOYMENT_STRATEGY_TYPE))
+    ),
 ):
     """Deploy a Modal application.
 

{modal-1.4.0 → modal-1.4.1}/modal/cli/shell.py

@@ -142,7 +142,11 @@ def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
 def _function_spec_from_ref(ref: str, use_module_mode: bool) -> _FunctionSpec:
     import_ref = parse_import_ref(ref, use_module_mode=use_module_mode)
     runnable, all_usable_commands = import_and_filter(
-        import_ref, base_cmd="modal shell", accept_local_entrypoint=False, accept_webhook=True
+        import_ref,
+        base_cmd="modal shell",
+        accept_local_entrypoint=False,
+        accept_webhook=True,
+        accept_service_functions=True,
     )
     if not runnable:
         help_header = (

{modal-1.4.0 → modal-1.4.1}/modal/client.py

@@ -22,7 +22,7 @@ from ._utils import async_utils
 from ._utils.async_utils import TaskContext, synchronize_api
 from ._utils.auth_token_manager import _AuthTokenManager
 from ._utils.grpc_utils import ConnectionManager
-from .config import _check_config, _is_remote, config, logger
+from .config import _agent_environment, _check_config, _is_remote, config, logger
 from .exception import AuthError, ClientClosed
 
 HEARTBEAT_INTERVAL: float = config.get("heartbeat_interval")
@@ -56,6 +56,8 @@ def _get_metadata(client_type: int, credentials: Optional[tuple[str, str]], vers
                 "x-modal-token-secret": token_secret,
             }
         )
+    if agent_env := _agent_environment():
+        metadata["x-modal-agent-harness"] = urllib.parse.quote(agent_env)
     return metadata
 
 

{modal-1.4.0 → modal-1.4.1}/modal/client.pyi

@@ -31,7 +31,7 @@ class _Client:
     client_type: int
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.4.0"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.4.1"
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -163,7 +163,7 @@ class Client:
     client_type: int
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.4.0"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.4.1"
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.4.0 → modal-1.4.1}/modal/config.py

@@ -121,6 +121,36 @@ def _is_remote() -> bool:
     return os.environ.get("MODAL_IS_REMOTE") == "1"
 
 
+def _agent_environment() -> Optional[str]:
+    """Detect if the current process is running inside an AI agent harness.
+
+    Returns the agent name if detected, or None otherwise.
+
+    Checks the emerging `AGENT` standard variable first, then falls back to
+    tool-specific environment variables used by known agent harnesses.
+    """
+    # Emerging standard: AGENT=<name>
+    if agent := os.environ.get("AGENT"):
+        return agent
+
+    # Tool-specific environment variables
+    _TOOL_SPECIFIC_ENV_VARS: list[tuple[str, str]] = [
+        ("CLAUDECODE", "claude-code"),
+        ("GEMINI_CLI", "gemini-cli"),
+        ("CURSOR_AGENT", "cursor"),
+        ("CLINE_ACTIVE", "cline"),
+        ("AUGMENT_AGENT", "augment"),
+        ("OPENCODE_CLIENT", "opencode"),
+        ("GOOSE_TERMINAL", "goose"),
+        ("TRAE_AI_SHELL_ID", "trae"),
+    ]
+    for env_var, agent_name in _TOOL_SPECIFIC_ENV_VARS:
+        if os.environ.get(env_var):
+            return agent_name
+
+    return None
+
+
 def _read_user_config():
     config_data = {}
     if not _is_remote() and os.path.exists(user_config_path):

{modal-1.4.0 → modal-1.4.1}/modal/dict.py

@@ -298,7 +298,8 @@ class _Dict(_Object, type_prefix="di"):
         )
 
     @classproperty
-    def objects(cls) -> _DictManager:
+    @classmethod
+    def objects(cls) -> type[_DictManager]:
         return _DictManager
 
     @property

{modal-1.4.0 → modal-1.4.1}/modal/dict.pyi

@@ -412,7 +412,8 @@ class _Dict(modal._object._Object):
         ...
 
     @synchronicity.classproperty
-    def objects(cls) -> _DictManager: ...
+    @classmethod
+    def objects(cls) -> type[_DictManager]: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
@@ -653,7 +654,8 @@ class Dict(modal.object.Object):
         ...
 
     @synchronicity.classproperty
-    def objects(cls) -> DictManager: ...
+    @classmethod
+    def objects(cls) -> type[DictManager]: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...

{modal-1.4.0 → modal-1.4.1}/modal/functions.pyi

@@ -348,7 +348,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         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."""
             ...
@@ -357,7 +357,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]
+    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -384,7 +384,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         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.
 
@@ -407,7 +407,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -415,7 +415,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         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.
 
@@ -436,7 +436,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
+    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

{modal-1.4.0 → modal-1.4.1}/modal/mount.py

@@ -699,16 +699,18 @@ Mount = synchronize_api(_Mount)
 
 def _create_client_mount():
     # TODO(erikbern): make this a static method on the Mount class
-    import synchronicity
+    import importlib
 
-    import modal
+    import synchronicity
 
-    # Get the base_path because it also contains `modal_proto`.
-    modal_parent_dir, _ = os.path.split(modal.__path__[0])
     client_mount = _Mount._new()
 
     for pkg_name in MODAL_PACKAGES:
-        package_base_path = Path(modal_parent_dir) / pkg_name
+        # Look up each package's actual install path via importlib rather than
+        # assuming all packages are siblings of `modal`. In Bazel runfiles,
+        # modal and modal_proto live in different directories.
+        pkg_module = importlib.import_module(pkg_name)
+        package_base_path = Path(pkg_module.__path__[0])
         client_mount = client_mount.add_local_dir(
             package_base_path,
             remote_path=f"/pkg/{pkg_name}",

{modal-1.4.0 → modal-1.4.1}/modal/queue.py

@@ -291,7 +291,8 @@ class _Queue(_Object, type_prefix="qu"):
         raise RuntimeError("Queue() is not allowed. Please use `Queue.from_name(...)` or `Queue.ephemeral()` instead.")
 
     @classproperty
-    def objects(cls) -> _QueueManager:
+    @classmethod
+    def objects(cls) -> type[_QueueManager]:
         return _QueueManager
 
     @property

{modal-1.4.0 → modal-1.4.1}/modal/queue.pyi

@@ -431,7 +431,8 @@ class _Queue(modal._object._Object):
         ...
 
     @synchronicity.classproperty
-    def objects(cls) -> _QueueManager: ...
+    @classmethod
+    def objects(cls) -> type[_QueueManager]: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
@@ -726,7 +727,8 @@ class Queue(modal.object.Object):
         ...
 
     @synchronicity.classproperty
-    def objects(cls) -> QueueManager: ...
+    @classmethod
+    def objects(cls) -> type[QueueManager]: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...

{modal-1.4.0 → modal-1.4.1}/modal/sandbox.py

@@ -42,6 +42,7 @@ from .exception import (
     InvalidError,
     SandboxTerminatedError,
     SandboxTimeoutError,
+    TimeoutError,
 )
 from .file_io import FileWatchEvent, FileWatchEventType, _FileIO, ls, mkdir, rm, watch
 from .image import _Image
@@ -118,6 +119,73 @@ class SandboxConnectCredentials:
     token: str
 
 
+@dataclass(frozen=True)
+class Probe:
+    """Probe configuration for the Sandbox Readiness Probe.
+
+    Usage:
+        ```py notest
+        # Wait until a file exists.
+        readiness_probe = modal.Probe.with_exec(
+            "sh", "-c", "test -f /tmp/ready",
+        )
+
+        # Wait until a TCP port is accepting connections.
+        readiness_probe = modal.Probe.with_tcp(8080)
+
+        app = modal.App.lookup('sandbox-readiness-probe', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=readiness_probe,
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+    """
+
+    tcp_port: Optional[int] = None
+    exec_argv: Optional[tuple[str, ...]] = None
+    interval_ms: int = 100
+
+    def __post_init__(self):
+        if (self.tcp_port is None) == (self.exec_argv is None):
+            raise InvalidError("Probe must be created with Probe.with_tcp(...) or Probe.with_exec(...)")
+
+    @classmethod
+    def with_tcp(cls, port: int, *, interval_ms: int = 100) -> "Probe":
+        if not isinstance(port, int):
+            raise InvalidError("Probe.with_tcp() expects an integer `port`")
+        if port <= 0 or port > 65535:
+            raise InvalidError(f"Probe.with_tcp() expects `port` in [1, 65535], got {port}")
+        if not isinstance(interval_ms, int):
+            raise InvalidError("Probe.with_tcp() expects an integer `interval_ms`")
+        if interval_ms <= 0:
+            raise InvalidError(f"Probe.with_tcp() expects `interval_ms` > 0, got {interval_ms}")
+        return cls(tcp_port=port, interval_ms=interval_ms)
+
+    @classmethod
+    def with_exec(cls, *argv: str, interval_ms: int = 100) -> "Probe":
+        if len(argv) == 0:
+            raise InvalidError("Probe.with_exec() requires at least one argument")
+        if not all(isinstance(arg, str) for arg in argv):
+            raise InvalidError("Probe.with_exec() expects all arguments to be strings")
+        if not isinstance(interval_ms, int):
+            raise InvalidError("Probe.with_exec() expects an integer `interval_ms`")
+        if interval_ms <= 0:
+            raise InvalidError(f"Probe.with_exec() expects `interval_ms` > 0, got {interval_ms}")
+        return cls(exec_argv=tuple(argv), interval_ms=interval_ms)
+
+    def _to_proto(self) -> api_pb2.Probe:
+        if self.tcp_port is not None:
+            return api_pb2.Probe(tcp_port=self.tcp_port, interval_ms=self.interval_ms)
+        if self.exec_argv is not None:
+            return api_pb2.Probe(
+                exec_command=api_pb2.Probe.ExecCommand(argv=list(self.exec_argv)),
+                interval_ms=self.interval_ms,
+            )
+        raise InvalidError("Probe must be created with Probe.with_tcp(...) or Probe.with_exec(...)")
+
+
 class _Sandbox(_Object, type_prefix="sb"):
     """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
     [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
@@ -166,6 +234,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         h2_ports: Sequence[int] = [],
         unencrypted_ports: Sequence[int] = [],
         proxy: Optional[_Proxy] = None,
+        readiness_probe: Optional[Probe] = None,
         experimental_options: Optional[dict[str, bool]] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
@@ -279,6 +348,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 open_ports=api_pb2.PortSpecs(ports=open_ports),
                 network_access=network_access,
                 proxy_id=(proxy.object_id if proxy else None),
+                readiness_probe=(readiness_probe._to_proto() if readiness_probe else None),
                 enable_snapshot=enable_snapshot,
                 verbose=verbose,
                 name=name,
@@ -339,6 +409,8 @@ class _Sandbox(_Object, type_prefix="sb"):
         proxy: Optional[_Proxy] = None,
         # If True, the sandbox will receive a MODAL_IDENTITY_TOKEN env var for OIDC-based auth.
         include_oidc_identity_token: bool = False,
+        # Probe used to determine when the sandbox has become ready.
+        readiness_probe: Optional[Probe] = None,
         # Enable verbose logging for sandbox operations.
         verbose: bool = False,
         experimental_options: Optional[dict[str, bool]] = None,
@@ -403,6 +475,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             h2_ports=h2_ports,
             unencrypted_ports=unencrypted_ports,
             proxy=proxy,
+            readiness_probe=readiness_probe,
             experimental_options=experimental_options,
             _experimental_enable_snapshot=_experimental_enable_snapshot,
             include_oidc_identity_token=include_oidc_identity_token,
@@ -439,6 +512,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         unencrypted_ports: Sequence[int] = [],
         proxy: Optional[_Proxy] = None,
         include_oidc_identity_token: bool = False,
+        readiness_probe: Optional[Probe] = None,
         experimental_options: Optional[dict[str, bool]] = None,
         _experimental_enable_snapshot: bool = False,
         client: Optional[_Client] = None,
@@ -490,6 +564,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             h2_ports=h2_ports,
             unencrypted_ports=unencrypted_ports,
             proxy=proxy,
+            readiness_probe=readiness_probe,
             experimental_options=experimental_options,
             enable_snapshot=_experimental_enable_snapshot,
             verbose=verbose,
@@ -958,6 +1033,39 @@ class _Sandbox(_Object, type_prefix="sb"):
                     raise SandboxTerminatedError()
                 break
 
+    async def wait_until_ready(self, *, timeout: int = 300) -> None:
+        """Wait for the Sandbox readiness probe to report that the Sandbox is ready.
+
+        The Sandbox must be configured with a `readiness_probe` in order to use this method.
+
+        Usage:
+        ```py notest
+        app = modal.App.lookup('sandbox-wait-until-ready', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=modal.Probe.with_tcp(8080),
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+        """
+        if timeout <= 0:
+            raise InvalidError(f"`timeout` must be positive, got: {timeout}")
+
+        deadline = time.monotonic() + timeout
+        remaining_timeout = deadline - time.monotonic()
+        while remaining_timeout > 0:
+            req = api_pb2.SandboxWaitUntilReadyRequest(
+                sandbox_id=self.object_id,
+                timeout=min(remaining_timeout, 50.0),
+            )
+            resp = await self._client.stub.SandboxWaitUntilReady(req)
+            if resp.ready_at > 0:
+                return
+
+            remaining_timeout = deadline - time.monotonic()
+        raise TimeoutError()
+
     async def tunnels(self, timeout: int = 50) -> dict[int, Tunnel]:
         """Get Tunnel metadata for the sandbox.