modAL 1.3.6.dev9__py3-none-any.whl → 1.3.6.dev10__py3-none-any.whl

modal/_utils/task_command_router_client.py

@@ -242,6 +242,44 @@ class TaskCommandRouterClient:
                 lambda: self._call_with_auth_retry(self._stub.TaskExecStart, request)
             )
 
+    async def container_create(self, request: sr_pb2.TaskContainerCreateRequest) -> sr_pb2.TaskContainerCreateResponse:
+        """Create an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerCreate, request)
+            )
+
+    async def container_terminate(
+        self,
+        request: sr_pb2.TaskContainerTerminateRequest,
+    ) -> sr_pb2.TaskContainerTerminateResponse:
+        """Terminate an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerTerminate, request)
+            )
+
+    async def container_wait(self, request: sr_pb2.TaskContainerWaitRequest) -> sr_pb2.TaskContainerWaitResponse:
+        """Wait for an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerWait, request)
+            )
+
+    async def container_get(self, request: sr_pb2.TaskContainerGetRequest) -> sr_pb2.TaskContainerGetResponse:
+        """Get the latest tracked container for a logical name via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerGet, request)
+            )
+
+    async def container_list(self, request: sr_pb2.TaskContainerListRequest) -> sr_pb2.TaskContainerListResponse:
+        """List sandbox containers via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerList, request)
+            )
+
     async def exec_stdio_read(
         self,
         task_id: str,

modal/cli/shell.py

@@ -18,6 +18,7 @@ from ..mount import _Mount
 from ..runner import interactive_shell
 from ..sandbox import Sandbox
 from ..secret import Secret
+from ..stream_type import StreamType
 from ..volume import Volume
 from .container import exec
 from .import_refs import (
@@ -64,26 +65,75 @@ def _is_valid_modal_id(ref: str, prefix: str) -> bool:
     return ref.startswith(prefix) and len(ref[len(prefix) :]) > 0 and ref[len(prefix) :].isalnum()
 
 
+def _parse_sandbox_container_ref(ref: str) -> tuple[str, Optional[str]]:
+    """Parse a sandbox:container reference into (sandbox_id, container_name).
+
+    Supports the pattern `sb-xyz:container_name` for accessing sandbox containers.
+    Returns (ref, None) if no container name is specified.
+    """
+    if _is_valid_modal_id(ref, "sb-"):
+        return ref, None
+
+    if ":" in ref:
+        parts = ref.split(":", 1)
+        sandbox_id, container_name = parts[0], parts[1]
+        if _is_valid_modal_id(sandbox_id, "sb-") and container_name:
+            return sandbox_id, container_name
+
+    return ref, None
+
+
 def _is_running_container_ref(ref: Optional[str]) -> bool:
     if ref is None:
         return False
-    return _is_valid_modal_id(ref, "sb-") or _is_valid_modal_id(ref, "ta-")
+    sandbox_id, _ = _parse_sandbox_container_ref(ref)
+    return _is_valid_modal_id(sandbox_id, "sb-") or _is_valid_modal_id(ref, "ta-")
+
+
+def _start_shell_in_sandbox_container(sandbox_id: str, container_name: str, cmd: str, pty: bool) -> None:
+    """Shell into a named container within a sandbox."""
+    try:
+        sandbox = Sandbox.from_id(sandbox_id)
+    except NotFoundError:
+        raise ClickException(f"Sandbox '{sandbox_id}' not found (is it still running?)")
+    except Exception as e:
+        raise ClickException(f"Error connecting to Sandbox '{sandbox_id}': {str(e)}")
+
+    try:
+        sandbox_container = sandbox._experimental_containers.get(name=container_name)
+        if pty:
+            process = sandbox_container.exec(*shlex.split(cmd), pty=pty)
+            process.attach()
+        else:
+            process = sandbox_container.exec(
+                *shlex.split(cmd), pty=pty, stdout=StreamType.STDOUT, stderr=StreamType.STDOUT
+            )
+            process.wait()
+    except NotFoundError:
+        raise ClickException(f"Container '{container_name}' not found in Sandbox '{sandbox_id}'.")
+    except Exception as e:
+        raise ClickException(f"Error exec-ing into container '{container_name}' in Sandbox '{sandbox_id}': {str(e)}")
 
 
 def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
-    if _is_valid_modal_id(ref, "sb-"):
+    sandbox_id, container_name = _parse_sandbox_container_ref(ref)
+
+    if container_name is not None:
+        return _start_shell_in_sandbox_container(sandbox_id, container_name, cmd, pty)
+
+    if _is_valid_modal_id(sandbox_id, "sb-"):
         try:
-            sandbox = Sandbox.from_id(ref)
+            sandbox = Sandbox.from_id(sandbox_id)
             ref = sandbox._get_task_id()
-        except NotFoundError as e:
-            raise ClickException(f"Sandbox '{ref}' not found (is it still running?)")
+        except NotFoundError:
+            raise ClickException(f"Sandbox '{sandbox_id}' not found (is it still running?)")
         except Exception as e:
-            raise ClickException(f"Error connecting to Sandbox '{ref}': {str(e)}")
+            raise ClickException(f"Error connecting to Sandbox '{sandbox_id}': {str(e)}")
 
     assert _is_valid_modal_id(ref, "ta-")
     try:
         exec(container_id=ref, command=shlex.split(cmd), pty=pty)
-    except NotFoundError as e:
+    except NotFoundError:
         raise ClickException(f"Container '{ref}' not found (is it still running?)")
     except Exception as e:
         raise ClickException(f"Error connecting to container '{ref}': {str(e)}")

modal/client.pyi

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

modal/sandbox.py

@@ -35,7 +35,14 @@ from ._utils.name_utils import check_object_name
 from ._utils.task_command_router_client import TaskCommandRouterClient
 from .client import _Client
 from .container_process import _ContainerProcess
-from .exception import ClientClosed, Error, ExecutionError, InvalidError, SandboxTerminatedError, SandboxTimeoutError
+from .exception import (
+    ClientClosed,
+    Error,
+    ExecutionError,
+    InvalidError,
+    SandboxTerminatedError,
+    SandboxTimeoutError,
+)
 from .file_io import FileWatchEvent, FileWatchEventType, _FileIO, ls, mkdir, rm, watch
 from .gpu import GPU_T
 from .image import _Image
@@ -68,6 +75,16 @@ if TYPE_CHECKING:
     import modal.app
 
 
+def _result_returncode(result: Optional[api_pb2.GenericResult]) -> Optional[int]:
+    if result is None or result.status == api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+        return None
+    if result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
+        return 124
+    if result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
+        return 137
+    return result.exitcode
+
+
 def _validate_exec_args(args: Sequence[str]) -> None:
     # Entrypoint args must be strings.
     if not all(isinstance(arg, str) for arg in args):
@@ -904,6 +921,12 @@ class _Sandbox(_Object, type_prefix="sb"):
             self._command_router_client = await TaskCommandRouterClient.try_init(self._client, task_id)
         return self._command_router_client
 
+    @property
+    def _experimental_containers(self) -> "_SandboxContainerManager":
+        """Manage additional containers running in this Sandbox."""
+        self._ensure_attached()
+        return _SandboxContainerManager(self)
+
     @overload
     async def exec(
         self,
@@ -1006,6 +1029,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         secrets: Optional[Collection[_Secret]] = None,
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Private method used internally.
 
@@ -1035,6 +1059,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             "text": text,
             "bufsize": bufsize,
             "runtime_debug": config.get("function_runtime_debug"),
+            "container_id": container_id,
         }
         # NB: This must come after the task ID is set, since the sandbox must be
         # scheduled before we can create a router client.
@@ -1057,8 +1082,11 @@ class _Sandbox(_Object, type_prefix="sb"):
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Execute a command through the Modal server."""
+        if container_id:
+            raise RuntimeError("Internal error: additional container exec requires task command router support")
         req = api_pb2.ContainerExecRequest(
             task_id=task_id,
             command=args,
@@ -1097,6 +1125,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Execute a command through a task command router running on the Modal worker."""
 
@@ -1134,6 +1163,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             secret_ids=secret_ids,
             pty_info=pty_info,
             runtime_debug=runtime_debug,
+            container_id=container_id or "",
         )
         _ = await command_router_client.exec_start(start_req)
 
@@ -1332,17 +1362,7 @@ class _Sandbox(_Object, type_prefix="sb"):
     @property
     def returncode(self) -> Optional[int]:
         """Return code of the Sandbox process if it has finished running, else `None`."""
-        if self._result is None or self._result.status == api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
-            return None
-
-        # Statuses are converted to exitcodes so we can conform to subprocess API.
-        # TODO: perhaps there should be a separate property that returns an enum directly?
-        elif self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
-            return 124
-        elif self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
-            return 137
-        else:
-            return self._result.exitcode
+        return _result_returncode(self._result)
 
     @staticmethod
     async def list(
@@ -1382,4 +1402,224 @@ class _Sandbox(_Object, type_prefix="sb"):
             before_timestamp = resp.sandboxes[-1].created_at
 
 
+class _SandboxContainer:
+    """Handle to an additional container running in a Sandbox."""
+
+    _result: Optional[api_pb2.GenericResult]
+
+    def __init__(
+        self,
+        sandbox: _Sandbox,
+        container_id: str,
+        container_name: str,
+        result: Optional[api_pb2.GenericResult] = None,
+    ) -> None:
+        self._sandbox = sandbox
+        self._container_id = container_id
+        self._container_name = container_name
+        self._result = result
+
+    @property
+    def object_id(self) -> str:
+        return self._container_id
+
+    @property
+    def name(self) -> str:
+        return self._container_name
+
+    @staticmethod
+    def _from_container_info(sandbox: "_Sandbox", container_info: sr_pb2.TaskContainerInfo) -> "_SandboxContainer":
+        result = container_info.result if container_info.HasField("result") else None
+        return _SandboxContainer(sandbox, container_info.container_id, container_info.container_name, result)
+
+    async def _get_command_router(self) -> tuple[str, "TaskCommandRouterClient"]:
+        """Get task ID and command router client, raising if unavailable."""
+        task_id = await self._sandbox._get_task_id()
+        command_router_client = await self._sandbox._get_command_router_client(task_id)
+        if command_router_client is None:
+            raise RuntimeError("Internal error: additional container operations require task command router support")
+        return task_id, command_router_client
+
+    async def exec(
+        self,
+        *args: str,
+        stdout: StreamType = StreamType.PIPE,
+        stderr: StreamType = StreamType.PIPE,
+        timeout: Optional[int] = None,
+        workdir: Optional[str] = None,
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        text: bool = True,
+        bufsize: Literal[-1, 1] = -1,
+        pty: bool = False,
+    ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
+        pty_info = self._sandbox._default_pty_info() if pty else None
+        return await self._sandbox._exec(
+            *args,
+            pty_info=pty_info,
+            stdout=stdout,
+            stderr=stderr,
+            timeout=timeout,
+            workdir=workdir,
+            env=env,
+            secrets=secrets,
+            text=text,
+            bufsize=bufsize,
+            container_id=self._container_id,
+        )
+
+    async def wait(self, raise_on_termination: bool = True) -> None:
+        if self._result is not None and self._result.status != api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+            if self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED and raise_on_termination:
+                raise SandboxTerminatedError()
+            return
+
+        task_id, command_router_client = await self._get_command_router()
+        while True:
+            resp = await command_router_client.container_wait(
+                sr_pb2.TaskContainerWaitRequest(
+                    task_id=task_id,
+                    container_id=self._container_id,
+                    timeout=10,
+                )
+            )
+            if resp.result.status:
+                self._result = resp.result
+                if resp.result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED and raise_on_termination:
+                    raise SandboxTerminatedError()
+                return
+
+    async def poll(self) -> Optional[int]:
+        if self._result is not None and self._result.status != api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+            return _result_returncode(self._result)
+
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_wait(
+            sr_pb2.TaskContainerWaitRequest(
+                task_id=task_id,
+                container_id=self._container_id,
+                timeout=0,
+            )
+        )
+        if resp.result.status:
+            self._result = resp.result
+        return _result_returncode(self._result)
+
+    @overload
+    async def terminate(
+        self,
+        *,
+        wait: Literal[True],
+    ) -> int: ...
+
+    @overload
+    async def terminate(
+        self,
+        *,
+        wait: Literal[False] = False,
+    ) -> None: ...
+
+    async def terminate(
+        self,
+        *,
+        wait: bool = False,
+    ) -> int | None:
+        task_id, command_router_client = await self._get_command_router()
+        await command_router_client.container_terminate(
+            sr_pb2.TaskContainerTerminateRequest(
+                task_id=task_id,
+                container_id=self._container_id,
+            )
+        )
+        if wait:
+            await self.wait(raise_on_termination=False)
+            return _result_returncode(self._result)
+
+
+class _SandboxContainerManager:
+    """Creates and manages additional containers in a Sandbox."""
+
+    def __init__(self, sandbox: _Sandbox) -> None:
+        self._sandbox = sandbox
+
+    async def _get_command_router(self) -> tuple[str, "TaskCommandRouterClient"]:
+        """Get task ID and command router client, raising if unavailable."""
+        task_id = await self._sandbox._get_task_id()
+        command_router_client = await self._sandbox._get_command_router_client(task_id)
+        if command_router_client is None:
+            raise RuntimeError("Internal error: additional container operations require task command router support")
+        return task_id, command_router_client
+
+    async def create(
+        self,
+        *args: str,
+        name: str,
+        image: _Image,
+        env: Optional[dict[str, str]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        workdir: Optional[str] = None,
+    ) -> _SandboxContainer:
+        if workdir is not None and not workdir.startswith("/"):
+            raise InvalidError(f"workdir must be an absolute path, got: {workdir}")
+        _validate_exec_args(args)
+
+        if image._mount_layers:
+            raise InvalidError(
+                "Sandbox._experimental_containers.create(image=...) only supports pre-built images. "
+                "When using `add_local*` methods, specify `copy=True` and call `.build()` before passing "
+                "the image to `._experimental_containers.create()`:\n\nE.g.\n"
+                'img = modal.Image.debian_slim().add_local_file("foo", "/foo", copy=True).build(app)\n'
+                'sandbox._experimental_containers.create(name="worker", image=img)'
+            )
+        if not image._object_id:
+            raise InvalidError(
+                "Sandbox._experimental_containers.create(image=...) currently only supports Images that are "
+                "either:\n"
+                "- prebuilt using `image.build()`\n"
+                "- referenced by id, e.g. `Image.from_id()`\n"
+                "- filesystem/directory snapshots e.g. created by `.snapshot_directory()` "
+                "or `.snapshot_filesystem()`\n"
+            )
+
+        secrets = secrets or []
+        secret_coros = [secret.hydrate(client=self._sandbox._client) for secret in secrets]
+        await TaskContext.gather(*secret_coros)
+
+        task_id, command_router_client = await self._get_command_router()
+
+        create_req = sr_pb2.TaskContainerCreateRequest(
+            task_id=task_id,
+            container_name=name,
+            image_id=image.object_id,
+            args=list(args),
+            env=env or {},
+            workdir=workdir or "",
+            secret_ids=[secret.object_id for secret in secrets],
+        )
+        create_resp = await command_router_client.container_create(create_req)
+        container_id = create_resp.container_id
+        container_name = create_resp.container_name or name
+        return _SandboxContainer(self._sandbox, container_id, container_name)
+
+    async def get(self, *, name: str, include_terminated: bool = False) -> "_SandboxContainer":
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_get(
+            sr_pb2.TaskContainerGetRequest(
+                task_id=task_id,
+                container_name=name,
+                include_terminated=include_terminated,
+            )
+        )
+        return _SandboxContainer._from_container_info(self._sandbox, resp.container)
+
+    async def list(self, include_terminated: bool = False) -> builtins.list[_SandboxContainer]:
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_list(
+            sr_pb2.TaskContainerListRequest(task_id=task_id, include_terminated=include_terminated)
+        )
+        return [_SandboxContainer._from_container_info(self._sandbox, container) for container in resp.containers]
+
+
+SandboxContainer = synchronize_api(_SandboxContainer)
+SandboxContainerManager = synchronize_api(_SandboxContainerManager)
 Sandbox = synchronize_api(_Sandbox)

modal/sandbox.pyi

@@ -22,11 +22,13 @@ import modal.snapshot
 import modal.stream_type
 import modal.volume
 import modal_proto.api_pb2
+import modal_proto.task_command_router_pb2
 import os
 import pathlib
 import typing
 import typing_extensions
 
+def _result_returncode(result: typing.Optional[modal_proto.api_pb2.GenericResult]) -> typing.Optional[int]: ...
 def _validate_exec_args(args: collections.abc.Sequence[str]) -> None: ...
 
 class DefaultSandboxNameOverride(str):
@@ -381,6 +383,11 @@ class _Sandbox(modal._object._Object):
     async def _get_command_router_client(
         self, task_id: str
     ) -> typing.Optional[modal._utils.task_command_router_client.TaskCommandRouterClient]: ...
+    @property
+    def _experimental_containers(self) -> _SandboxContainerManager:
+        """Manage additional containers running in this Sandbox."""
+        ...
+
     @typing.overload
     async def exec(
         self,
@@ -425,6 +432,7 @@ class _Sandbox(modal._object._Object):
         secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         text: bool = True,
         bufsize: typing.Literal[-1, 1] = -1,
+        container_id: typing.Optional[str] = None,
     ) -> typing.Union[modal.container_process._ContainerProcess[bytes], modal.container_process._ContainerProcess[str]]:
         """Private method used internally.
 
@@ -445,6 +453,7 @@ class _Sandbox(modal._object._Object):
         text: bool = True,
         bufsize: typing.Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: typing.Optional[str] = None,
     ) -> typing.Union[modal.container_process._ContainerProcess[bytes], modal.container_process._ContainerProcess[str]]:
         """Execute a command through the Modal server."""
         ...
@@ -463,6 +472,7 @@ class _Sandbox(modal._object._Object):
         text: bool = True,
         bufsize: typing.Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: typing.Optional[str] = None,
     ) -> typing.Union[modal.container_process._ContainerProcess[bytes], modal.container_process._ContainerProcess[str]]:
         """Execute a command through a task command router running on the Modal worker."""
         ...
@@ -546,6 +556,220 @@ class _Sandbox(modal._object._Object):
         """
         ...
 
+class _SandboxContainer:
+    """Handle to an additional container running in a Sandbox."""
+
+    _result: typing.Optional[modal_proto.api_pb2.GenericResult]
+
+    def __init__(
+        self,
+        sandbox: _Sandbox,
+        container_id: str,
+        container_name: str,
+        result: typing.Optional[modal_proto.api_pb2.GenericResult] = None,
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    @property
+    def object_id(self) -> str: ...
+    @property
+    def name(self) -> str: ...
+    @staticmethod
+    def _from_container_info(
+        sandbox: _Sandbox, container_info: modal_proto.task_command_router_pb2.TaskContainerInfo
+    ) -> _SandboxContainer: ...
+    async def _get_command_router(self) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+        """Get task ID and command router client, raising if unavailable."""
+        ...
+
+    async def exec(
+        self,
+        *args: str,
+        stdout: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+        stderr: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+        timeout: typing.Optional[int] = None,
+        workdir: typing.Optional[str] = None,
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
+        text: bool = True,
+        bufsize: typing.Literal[-1, 1] = -1,
+        pty: bool = False,
+    ) -> typing.Union[
+        modal.container_process._ContainerProcess[bytes], modal.container_process._ContainerProcess[str]
+    ]: ...
+    async def wait(self, raise_on_termination: bool = True) -> None: ...
+    async def poll(self) -> typing.Optional[int]: ...
+    @typing.overload
+    async def terminate(self, *, wait: typing.Literal[True]) -> int: ...
+    @typing.overload
+    async def terminate(self, *, wait: typing.Literal[False] = False) -> None: ...
+
+class _SandboxContainerManager:
+    """Creates and manages additional containers in a Sandbox."""
+    def __init__(self, sandbox: _Sandbox) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    async def _get_command_router(self) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+        """Get task ID and command router client, raising if unavailable."""
+        ...
+
+    async def create(
+        self,
+        *args: str,
+        name: str,
+        image: modal.image._Image,
+        env: typing.Optional[dict[str, str]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
+        workdir: typing.Optional[str] = None,
+    ) -> _SandboxContainer: ...
+    async def get(self, *, name: str, include_terminated: bool = False) -> _SandboxContainer: ...
+    async def list(self, include_terminated: bool = False) -> list[_SandboxContainer]: ...
+
+class SandboxContainer:
+    """Handle to an additional container running in a Sandbox."""
+
+    _result: typing.Optional[modal_proto.api_pb2.GenericResult]
+
+    def __init__(
+        self,
+        sandbox: Sandbox,
+        container_id: str,
+        container_name: str,
+        result: typing.Optional[modal_proto.api_pb2.GenericResult] = None,
+    ) -> None: ...
+    @property
+    def object_id(self) -> str: ...
+    @property
+    def name(self) -> str: ...
+    @staticmethod
+    def _from_container_info(
+        sandbox: Sandbox, container_info: modal_proto.task_command_router_pb2.TaskContainerInfo
+    ) -> SandboxContainer: ...
+
+    class ___get_command_router_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+            """Get task ID and command router client, raising if unavailable."""
+            ...
+
+        async def aio(self, /) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+            """Get task ID and command router client, raising if unavailable."""
+            ...
+
+    _get_command_router: ___get_command_router_spec
+
+    class __exec_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *args: str,
+            stdout: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+            stderr: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+            timeout: typing.Optional[int] = None,
+            workdir: typing.Optional[str] = None,
+            env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+            secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
+            text: bool = True,
+            bufsize: typing.Literal[-1, 1] = -1,
+            pty: bool = False,
+        ) -> typing.Union[
+            modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
+        ]: ...
+        async def aio(
+            self,
+            /,
+            *args: str,
+            stdout: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+            stderr: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+            timeout: typing.Optional[int] = None,
+            workdir: typing.Optional[str] = None,
+            env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+            secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
+            text: bool = True,
+            bufsize: typing.Literal[-1, 1] = -1,
+            pty: bool = False,
+        ) -> typing.Union[
+            modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
+        ]: ...
+
+    exec: __exec_spec
+
+    class __wait_spec(typing_extensions.Protocol):
+        def __call__(self, /, raise_on_termination: bool = True) -> None: ...
+        async def aio(self, /, raise_on_termination: bool = True) -> None: ...
+
+    wait: __wait_spec
+
+    class __poll_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> typing.Optional[int]: ...
+        async def aio(self, /) -> typing.Optional[int]: ...
+
+    poll: __poll_spec
+
+    class __terminate_spec(typing_extensions.Protocol):
+        @typing.overload
+        def __call__(self, /, *, wait: typing.Literal[True]) -> int: ...
+        @typing.overload
+        def __call__(self, /, *, wait: typing.Literal[False] = False) -> None: ...
+        @typing.overload
+        async def aio(self, /, *, wait: typing.Literal[True]) -> int: ...
+        @typing.overload
+        async def aio(self, /, *, wait: typing.Literal[False] = False) -> None: ...
+
+    terminate: __terminate_spec
+
+class SandboxContainerManager:
+    """Creates and manages additional containers in a Sandbox."""
+    def __init__(self, sandbox: Sandbox) -> None: ...
+
+    class ___get_command_router_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+            """Get task ID and command router client, raising if unavailable."""
+            ...
+
+        async def aio(self, /) -> tuple[str, modal._utils.task_command_router_client.TaskCommandRouterClient]:
+            """Get task ID and command router client, raising if unavailable."""
+            ...
+
+    _get_command_router: ___get_command_router_spec
+
+    class __create_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *args: str,
+            name: str,
+            image: modal.image.Image,
+            env: typing.Optional[dict[str, str]] = None,
+            secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
+            workdir: typing.Optional[str] = None,
+        ) -> SandboxContainer: ...
+        async def aio(
+            self,
+            /,
+            *args: str,
+            name: str,
+            image: modal.image.Image,
+            env: typing.Optional[dict[str, str]] = None,
+            secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
+            workdir: typing.Optional[str] = None,
+        ) -> SandboxContainer: ...
+
+    create: __create_spec
+
+    class __get_spec(typing_extensions.Protocol):
+        def __call__(self, /, *, name: str, include_terminated: bool = False) -> SandboxContainer: ...
+        async def aio(self, /, *, name: str, include_terminated: bool = False) -> SandboxContainer: ...
+
+    get: __get_spec
+
+    class __list_spec(typing_extensions.Protocol):
+        def __call__(self, /, include_terminated: bool = False) -> list[SandboxContainer]: ...
+        async def aio(self, /, include_terminated: bool = False) -> list[SandboxContainer]: ...
+
+    list: __list_spec
+
 class Sandbox(modal.object.Object):
     """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).
@@ -1179,6 +1403,11 @@ class Sandbox(modal.object.Object):
 
     _get_command_router_client: ___get_command_router_client_spec
 
+    @property
+    def _experimental_containers(self) -> SandboxContainerManager:
+        """Manage additional containers running in this Sandbox."""
+        ...
+
     class __exec_spec(typing_extensions.Protocol):
         @typing.overload
         def __call__(
@@ -1265,6 +1494,7 @@ class Sandbox(modal.object.Object):
             secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:
@@ -1287,6 +1517,7 @@ class Sandbox(modal.object.Object):
             secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:
@@ -1313,6 +1544,7 @@ class Sandbox(modal.object.Object):
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
             runtime_debug: bool = False,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:
@@ -1333,6 +1565,7 @@ class Sandbox(modal.object.Object):
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
             runtime_debug: bool = False,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:
@@ -1357,6 +1590,7 @@ class Sandbox(modal.object.Object):
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
             runtime_debug: bool = False,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:
@@ -1378,6 +1612,7 @@ class Sandbox(modal.object.Object):
             text: bool = True,
             bufsize: typing.Literal[-1, 1] = -1,
             runtime_debug: bool = False,
+            container_id: typing.Optional[str] = None,
         ) -> typing.Union[
             modal.container_process.ContainerProcess[bytes], modal.container_process.ContainerProcess[str]
         ]:

{modal-1.3.6.dev9.dist-info → modal-1.3.6.dev10.dist-info}/METADATA

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

{modal-1.3.6.dev9.dist-info → modal-1.3.6.dev10.dist-info}/RECORD

@@ -26,7 +26,7 @@ modal/app.pyi,sha256=8lv2eLKP-y3BLT1irRnzdULSD45OgU4_VbCIYEy_Ic0,56387
 modal/billing.py,sha256=B2zXa7KeMnpqi2AQINycEk-KSXVYaLTTTAQTtuf2Gfs,257
 modal/call_graph.py,sha256=1g2DGcMIJvRy-xKicuf63IVE98gJSnQsr8R_NVMptNc,2581
 modal/client.py,sha256=-IxazxLhdkNFAHS2AP2FpyTVpCDVR58RF6ecSVV59r0,14862
-modal/client.pyi,sha256=jYNvLifQve3TLlDOeU6KfuzXRxzFUDvv4mEU5nARI3w,14930
+modal/client.pyi,sha256=ut6XUIpQGf73KLfo5x6eTZc7OrQkbKHQoYeR42zmdo8,14932
 modal/cloud_bucket_mount.py,sha256=KkaJVy5vpO_u2NtDYtv1JM-M3y4J0UtWBapTDKpQRcA,6034
 modal/cloud_bucket_mount.pyi,sha256=mGDeEd1XvxGpCE6O5jRBSfIvMXvZ5AtIybea5k-0w9w,7560
 modal/cls.py,sha256=ozx5ZVGyG6w5SQ1ouj9Y6M3yPtnpL9PfblnmqFzf694,42338
@@ -69,8 +69,8 @@ modal/retries.py,sha256=vPWWKP-FRolJwTBuLPXdWqHV7aJfSQFgEW7vhlBBXRQ,5067
 modal/runner.py,sha256=rz3th7ZtN-UlUe7RO38J89gg4XtFlbBrSq4cOGIl1Eg,29594
 modal/runner.pyi,sha256=UgV8jEjoRgnIowZHnOWrbGjZFsLCDm6D-4gpf77H4so,9517
 modal/running_app.py,sha256=v61mapYNV1-O-Uaho5EfJlryMLvIT9We0amUOSvSGx8,1188
-modal/sandbox.py,sha256=uFU5zT2lOgGeuZRqL8CEpzO6VVGQIS0zpibfc1FUxYA,58218
-modal/sandbox.pyi,sha256=LvF04EgeFCywCigcWZEEzgBRosEv5WrkPtCD4ggy--Q,66905
+modal/sandbox.py,sha256=lJlx5FHait0BYB2anXc0ciiy78NwAWwKYszQdA6jXhA,67572
+modal/sandbox.pyi,sha256=MLPfBwHxg6EpplMjky44lhNPDb0HDFxBuImJleTJvqU,76610
 modal/sandbox_fs.py,sha256=mEgfFKGgLFO7Ncvw_iQc54htHZ66E1i56ADNnXj9NHQ,13080
 modal/sandbox_fs.pyi,sha256=qr3PWlWwHqKRa_fPe9aI2ecj-iNF-NKY52GaL_MXc1U,21245
 modal/schedule.py,sha256=ng0g0AqNY5GQI9KhkXZQ5Wam5G42glbkqVQsNpBtbDE,3078
@@ -127,7 +127,7 @@ modal/_utils/pattern_utils.py,sha256=ZUffaECfe2iYBhH6cvCB-0-UWhmEBTZEl_TwG_So3ag
 modal/_utils/rand_pb_testing.py,sha256=oNtQB1BY9CDh7vDXEkJitCuCu9a2ufk0KRcEuZ15d0k,4229
 modal/_utils/sandbox_fs_utils.py,sha256=BZQXwfWMQHXTw_5u1ttbb2Ouxxbe3W7DaJDTJZPbMAs,6536
 modal/_utils/shell_utils.py,sha256=GjMrO1YxnBr4_UlpA2ZYQKCHxV78QTg0mqxAMHWGTE4,3427
-modal/_utils/task_command_router_client.py,sha256=BnlOtEtFTwJFDaCDMlu21PSj0Y4AloboyJObmnRCwqM,23347
+modal/_utils/task_command_router_client.py,sha256=VLzjgwdSFZvub6MxsjsWtx2a4UwI2SCbK5-K4GGpHz0,25363
 modal/_utils/time_utils.py,sha256=VVrIwm7YMv2vMznNGknkGzyATDp5iJ29F_7NZPfm5b0,7062
 modal/_vendor/__init__.py,sha256=MIEP8jhXUeGq_eCjYFcqN5b1bxBM4fdk0VESpjWR0fc,28
 modal/_vendor/a2wsgi_wsgi.py,sha256=Q1AsjpV_Q_vzQsz_cSqmP9jWzsGsB-ARFU6vpQYml8k,21878
@@ -163,7 +163,7 @@ modal/cli/queues.py,sha256=0sl1aydtudoH9RYLyUAK7FJSJ8oCtgYkkENQJ_7ifXc,6230
 modal/cli/run.py,sha256=kpdTvbNa3jvxJGYmIt6Eh5MJjLPctFusfK2Tq8jOWbM,21389
 modal/cli/secret.py,sha256=yBpjzzkbA2dNb_Q_2qqltMvCfhzUxDH7-xehLiqrvhI,8061
 modal/cli/selector.py,sha256=2P4fAgvntNLBJaMjZdDHHopCSoefHKpCMfKGzXzk9jc,4178
-modal/cli/shell.py,sha256=L5Dw8yeuu9-f6vNlBGbUT4oh9AVSK4GuB5J6m6vYLBk,12613
+modal/cli/shell.py,sha256=oJT5U7ZTW7KJZ2cFl44su_zrbsvaPJKWAWvwuCEX3CQ,14663
 modal/cli/token.py,sha256=KIEOgHJ-k1t2h6tolBmQJSSOJlpU3kvmH_IKQzaHhig,4098
 modal/cli/utils.py,sha256=aLTpttgH2lkOAC6HRtaAMCIKgo-zluvC_d-yQ3gsrz4,6462
 modal/cli/volume.py,sha256=Tp97ekMTEHT0NXwgyEudO8yIZ75OGOfjIfH44WS5r9Y,11026
@@ -174,7 +174,7 @@ modal/experimental/__init__.py,sha256=4UyAPlExXYM0tJH7s6WSDt2dIfSVXvzARkRLsLMyuq
 modal/experimental/flash.py,sha256=ATGhVO8AleJ-TOe2PGolI5T7zfCEtj0kl_ivMPp7Rqg,33362
 modal/experimental/flash.pyi,sha256=R4h2nQl7-oiwqq_twCp0YqID_LnPjPGqxywXvxbiLIk,17011
 modal/experimental/ipython.py,sha256=TrCfmol9LGsRZMeDoeMPx3Hv3BFqQhYnmD_iH0pqdhk,2904
-modal-1.3.6.dev9.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-1.3.6.dev10.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
 modal_docs/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/gen_cli_docs.py,sha256=5sVABw4uGUqPXjcWT0Nqjkpe5KLs89C3tFnla58-D0M,3756
 modal_docs/gen_cli_docs_main.py,sha256=UPGr7O1DYTIRLwfINe2rbdh89J3cPVTU1OWL-SjxnOQ,198
@@ -196,10 +196,10 @@ modal_proto/task_command_router_pb2.py,sha256=uSSR8Y9Yp07cIL60ds7__wUr5rj1uL2CQY
 modal_proto/task_command_router_pb2.pyi,sha256=utNwipYgMZUEUuWBE7sJ5cNjRctozHKPKDRpLy6cPLM,25667
 modal_proto/task_command_router_pb2_grpc.py,sha256=YoinPeLc-uwFShig8gE0MluOi6n-qqJZQ3YvnKwKUz8,23194
 modal_proto/task_command_router_pb2_grpc.pyi,sha256=VUSE5l1O6ATPT8Wbj4M3faMiIy5vFxSoS5ZlKfTEpHc,7449
-modal_version/__init__.py,sha256=mxS-hT7DtmdHGbRDYQRsbpyTBhA7g0YMOsezQo15t2A,120
+modal_version/__init__.py,sha256=1Wfo-F7lJ0XaY1v8peKaecTUR3Pn0XJfD1xUVedGfLc,121
 modal_version/__main__.py,sha256=nLUbubxKx7GXNzJIkTB7M7_u8080LyLM0IS0rzFkC_c,119
-modal-1.3.6.dev9.dist-info/METADATA,sha256=cb0Idkuh_5XTvizbMIqfUckFqXYgYhQFwIvAimKCuIk,2364
-modal-1.3.6.dev9.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
-modal-1.3.6.dev9.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-1.3.6.dev9.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
-modal-1.3.6.dev9.dist-info/RECORD,,
+modal-1.3.6.dev10.dist-info/METADATA,sha256=ESSWZgUHODQ12XLEpz04vhV9AFdMd98V_UZ466knejI,2365
+modal-1.3.6.dev10.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+modal-1.3.6.dev10.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-1.3.6.dev10.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
+modal-1.3.6.dev10.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.3.6.dev9"
+__version__ = "1.3.6.dev10"