modal 0.62.115__py3-none-any.whl → 0.72.13__py3-none-any.whl

modal/sandbox.py

@@ -1,13 +1,17 @@
 # Copyright Modal Labs 2022
 import asyncio
 import os
-from typing import AsyncIterator, Dict, List, Optional, Sequence, Tuple, Union
+from collections.abc import AsyncGenerator, Sequence
+from typing import TYPE_CHECKING, AsyncIterator, Literal, Optional, Union, overload
+
+if TYPE_CHECKING:
+    import _typeshed
 
 from google.protobuf.message import Message
-from grpclib.exceptions import GRPCError, StreamTerminatedError
+from grpclib import GRPCError, Status
 
+from modal._tunnel import Tunnel
 from modal.cloud_bucket_mount import _CloudBucketMount, cloud_bucket_mounts_to_proto
-from modal.exception import InvalidError, SandboxTerminatedError, SandboxTimeoutError
 from modal.volume import _Volume
 from modal_proto import api_pb2
 
@@ -15,209 +19,30 @@ from ._location import parse_cloud_provider
 from ._resolver import Resolver
 from ._resources import convert_fn_config_to_resources_config
 from ._utils.async_utils import synchronize_api
-from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES, retry_transient_errors, unary_stream
-from ._utils.mount_utils import validate_mount_points, validate_volumes
+from ._utils.deprecation import deprecation_error
+from ._utils.grpc_utils import retry_transient_errors
+from ._utils.mount_utils import validate_network_file_systems, validate_volumes
 from .client import _Client
 from .config import config
+from .container_process import _ContainerProcess
+from .exception import ExecutionError, InvalidError, SandboxTerminatedError, SandboxTimeoutError
+from .file_io import FileWatchEvent, FileWatchEventType, _FileIO
 from .gpu import GPU_T
 from .image import _Image
+from .io_streams import StreamReader, StreamWriter, _StreamReader, _StreamWriter
 from .mount import _Mount
 from .network_file_system import _NetworkFileSystem, network_file_system_mount_protos
-from .object import _Object
+from .object import _get_environment_name, _Object
+from .proxy import _Proxy
 from .scheduler_placement import SchedulerPlacement
 from .secret import _Secret
+from .stream_type import StreamType
 
+_default_image: _Image = _Image.debian_slim()
 
-class _LogsReader:
-    """Provides an interface to buffer and fetch logs from a sandbox stream (`stdout` or `stderr`).
-
-    As an asynchronous iterable, the object supports the async for statement.
-
-    **Usage**
-
-    ```python
-    @app.function()
-    async def my_fn():
-        sandbox = app.spawn_sandbox(
-            "bash",
-            "-c",
-            "while true; do echo foo; sleep 1; done"
-        )
-        async for message in sandbox.stdout:
-            print(f"Message: {message}")
-    ```
-    """
-
-    def __init__(self, file_descriptor: int, sandbox_id: str, client: _Client) -> None:
-        """mdmd:hidden"""
-
-        self._file_descriptor = file_descriptor
-        self._sandbox_id = sandbox_id
-        self._client = client
-        self._stream = None
-        self._last_log_batch_entry_id = ""
-        # Whether the reader received an EOF. Once EOF is True, it returns
-        # an empty string for any subsequent reads (including async for)
-        self.eof = False
-
-    async def read(self) -> str:
-        """Fetch and return contents of the entire stream. If EOF was received,
-        return an empty string.
-
-        **Usage**
-
-        ```python
-        sandbox = app.app.spawn_sandbox("echo", "hello")
-        sandbox.wait()
-
-        print(sandbox.stdout.read())
-        ```
-
-        """
-        data = ""
-        # TODO: maybe combine this with get_app_logs_loop
-        async for message in self._get_logs():
-            if message is None:
-                break
-            data += message.data
-
-        return data
-
-    async def _get_logs(self) -> AsyncIterator[Optional[api_pb2.TaskLogs]]:
-        """mdmd:hidden
-        Streams sandbox logs from the server to the reader.
-
-        When the stream receives an EOF, it yields None. Once an EOF is received,
-        subsequent invocations will not yield logs.
-        """
-        if self.eof:
-            yield None
-            return
-
-        completed = False
-
-        retries_remaining = 10
-        while not completed:
-            req = api_pb2.SandboxGetLogsRequest(
-                sandbox_id=self._sandbox_id,
-                file_descriptor=self._file_descriptor,
-                timeout=55,
-                last_entry_id=self._last_log_batch_entry_id,
-            )
-            try:
-                async for log_batch in unary_stream(self._client.stub.SandboxGetLogs, req):
-                    self._last_log_batch_entry_id = log_batch.entry_id
-
-                    for message in log_batch.items:
-                        yield message
-                    if log_batch.eof:
-                        self.eof = True
-                        completed = True
-                        yield None
-                        break
-            except (GRPCError, StreamTerminatedError) as exc:
-                if retries_remaining > 0:
-                    retries_remaining -= 1
-                    if isinstance(exc, GRPCError):
-                        if exc.status in RETRYABLE_GRPC_STATUS_CODES:
-                            await asyncio.sleep(1.0)
-                            continue
-                    elif isinstance(exc, StreamTerminatedError):
-                        continue
-                raise
-
-    def __aiter__(self):
-        """mdmd:hidden"""
-        self._stream = self._get_logs()
-        return self
-
-    async def __anext__(self):
-        """mdmd:hidden"""
-        value = await self._stream.__anext__()
-
-        # The stream yields None if it receives an EOF batch.
-        if value is None:
-            raise StopAsyncIteration
-
-        return value.data
-
-
-MAX_BUFFER_SIZE = 128 * 1024
 
-
-class _StreamWriter:
-    """Provides an interface to buffer and write logs to a sandbox stream (`stdin`)."""
-
-    def __init__(self, sandbox_id: str, client: _Client):
-        self._index = 1
-        self._sandbox_id = sandbox_id
-        self._client = client
-        self._is_closed = False
-        self._buffer = bytearray()
-
-    def get_next_index(self):
-        """mdmd:hidden"""
-        index = self._index
-        self._index += 1
-        return index
-
-    def write(self, data: Union[bytes, bytearray, memoryview]):
-        """
-        Writes data to stream's internal buffer, but does not drain/flush the write.
-
-        This method needs to be used along with the `drain()` method which flushes the buffer.
-
-        **Usage**
-
-        ```python
-        @app.local_entrypoint()
-        def main():
-            sandbox = app.spawn_sandbox(
-                "bash",
-                "-c",
-                "while read line; do echo $line; done",
-            )
-            sandbox.stdin.write(b"foo\\n")
-            sandbox.stdin.write(b"bar\\n")
-            sandbox.stdin.write_eof()
-
-            sandbox.stdin.drain()
-            sandbox.wait()
-        ```
-        """
-        if self._is_closed:
-            raise EOFError("Stdin is closed. Cannot write to it.")
-        if isinstance(data, (bytes, bytearray, memoryview)):
-            if len(self._buffer) + len(data) > MAX_BUFFER_SIZE:
-                raise BufferError("Buffer size exceed limit. Call drain to clear the buffer.")
-            self._buffer.extend(data)
-        else:
-            raise TypeError(f"data argument must be a bytes-like object, not {type(data).__name__}")
-
-    def write_eof(self):
-        """
-        Closes the write end of the stream after the buffered write data is drained.
-        If the sandbox process was blocked on input, it will become unblocked after `write_eof()`.
-
-        This method needs to be used along with the `drain()` method which flushes the EOF to the process.
-        """
-        self._is_closed = True
-
-    async def drain(self):
-        """
-        Flushes the write buffer and EOF to the running Sandbox process.
-        """
-        data = bytes(self._buffer)
-        self._buffer.clear()
-        index = self.get_next_index()
-        await retry_transient_errors(
-            self._client.stub.SandboxStdinWrite,
-            api_pb2.SandboxStdinWriteRequest(sandbox_id=self._sandbox_id, index=index, eof=self._is_closed, input=data),
-        )
-
-
-LogsReader = synchronize_api(_LogsReader)
-StreamWriter = synchronize_api(_StreamWriter)
+if TYPE_CHECKING:
+    import modal.app
 
 
 class _Sandbox(_Object, type_prefix="sb"):
@@ -228,9 +53,11 @@ class _Sandbox(_Object, type_prefix="sb"):
     """
 
     _result: Optional[api_pb2.GenericResult]
-    _stdout: _LogsReader
-    _stderr: _LogsReader
+    _stdout: _StreamReader[str]
+    _stderr: _StreamReader[str]
     _stdin: _StreamWriter
+    _task_id: Optional[str] = None
+    _tunnels: Optional[dict[int, Tunnel]] = None
 
     @staticmethod
     def _new(
@@ -242,14 +69,17 @@ class _Sandbox(_Object, type_prefix="sb"):
         workdir: Optional[str] = None,
         gpu: GPU_T = None,
         cloud: Optional[str] = None,
+        region: Optional[Union[str, Sequence[str]]] = None,
         cpu: Optional[float] = None,
-        memory: Optional[Union[int, Tuple[int, int]]] = None,
-        network_file_systems: Dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
+        memory: Optional[Union[int, tuple[int, int]]] = None,
+        network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
         block_network: bool = False,
-        volumes: Dict[Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]] = {},
-        allow_background_volume_commits: bool = False,
+        cidr_allowlist: Optional[Sequence[str]] = None,
+        volumes: dict[Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]] = {},
         pty_info: Optional[api_pb2.PTYInfo] = None,
-        _experimental_scheduler: bool = False,
+        encrypted_ports: Sequence[int] = [],
+        unencrypted_ports: Sequence[int] = [],
+        proxy: Optional[_Proxy] = None,
         _experimental_scheduler_placement: Optional[SchedulerPlacement] = None,
     ) -> "_Sandbox":
         """mdmd:hidden"""
@@ -257,17 +87,30 @@ class _Sandbox(_Object, type_prefix="sb"):
         if len(entrypoint_args) == 0:
             raise InvalidError("entrypoint_args must not be empty")
 
-        if not isinstance(network_file_systems, dict):
-            raise InvalidError("network_file_systems must be a dict[str, NetworkFileSystem] where the keys are paths")
-        validated_network_file_systems = validate_mount_points("Network file system", network_file_systems)
+        validated_network_file_systems = validate_network_file_systems(network_file_systems)
+
+        scheduler_placement: Optional[SchedulerPlacement] = _experimental_scheduler_placement
+        if region:
+            if scheduler_placement:
+                raise InvalidError("`region` and `_experimental_scheduler_placement` cannot be used together")
+            scheduler_placement = SchedulerPlacement(region=region)
+
+        if isinstance(gpu, list):
+            raise InvalidError(
+                "Sandboxes do not support configuring a list of GPUs. "
+                "Specify a single GPU configuration, e.g. gpu='a10g'"
+            )
+
+        if workdir is not None and not workdir.startswith("/"):
+            raise InvalidError(f"workdir must be an absolute path, got: {workdir}")
 
         # Validate volumes
         validated_volumes = validate_volumes(volumes)
         cloud_bucket_mounts = [(k, v) for k, v in validated_volumes if isinstance(v, _CloudBucketMount)]
         validated_volumes = [(k, v) for k, v in validated_volumes if isinstance(v, _Volume)]
 
-        def _deps() -> List[_Object]:
-            deps: List[_Object] = [image] + list(mounts) + list(secrets)
+        def _deps() -> list[_Object]:
+            deps: list[_Object] = [image] + list(mounts) + list(secrets)
             for _, vol in validated_network_file_systems:
                 deps.append(vol)
             for _, vol in validated_volumes:
@@ -275,6 +118,8 @@ class _Sandbox(_Object, type_prefix="sb"):
             for _, cloud_bucket_mount in cloud_bucket_mounts:
                 if cloud_bucket_mount.secret:
                     deps.append(cloud_bucket_mount.secret)
+            if proxy:
+                deps.append(proxy)
             return deps
 
         async def _load(self: _Sandbox, resolver: Resolver, _existing_object_id: Optional[str]):
@@ -283,33 +128,60 @@ class _Sandbox(_Object, type_prefix="sb"):
                 api_pb2.VolumeMount(
                     mount_path=path,
                     volume_id=volume.object_id,
-                    allow_background_commits=allow_background_volume_commits,
+                    allow_background_commits=True,
                 )
                 for path, volume in validated_volumes
             ]
 
+            open_ports = [api_pb2.PortSpec(port=port, unencrypted=False) for port in encrypted_ports]
+            open_ports.extend([api_pb2.PortSpec(port=port, unencrypted=True) for port in unencrypted_ports])
+
+            if block_network:
+                # If the network is blocked, cidr_allowlist is invalid as we don't allow any network access.
+                if cidr_allowlist is not None:
+                    raise InvalidError("`cidr_allowlist` cannot be used when `block_network` is enabled")
+                network_access = api_pb2.NetworkAccess(
+                    network_access_type=api_pb2.NetworkAccess.NetworkAccessType.BLOCKED,
+                )
+            elif cidr_allowlist is None:
+                # If the allowlist is empty, we allow all network access.
+                network_access = api_pb2.NetworkAccess(
+                    network_access_type=api_pb2.NetworkAccess.NetworkAccessType.OPEN,
+                )
+            else:
+                network_access = api_pb2.NetworkAccess(
+                    network_access_type=api_pb2.NetworkAccess.NetworkAccessType.ALLOWLIST,
+                    allowed_cidrs=cidr_allowlist,
+                )
+
+            ephemeral_disk = None  # Ephemeral disk requests not supported on Sandboxes.
             definition = api_pb2.Sandbox(
                 entrypoint_args=entrypoint_args,
                 image_id=image.object_id,
-                mount_ids=[mount.object_id for mount in mounts],
+                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,
                 workdir=workdir,
-                resources=convert_fn_config_to_resources_config(cpu=cpu, memory=memory, gpu=gpu),
+                resources=convert_fn_config_to_resources_config(
+                    cpu=cpu, memory=memory, gpu=gpu, ephemeral_disk=ephemeral_disk
+                ),
                 cloud_provider=parse_cloud_provider(cloud) if cloud else None,
                 nfs_mounts=network_file_system_mount_protos(validated_network_file_systems, False),
                 runtime_debug=config.get("function_runtime_debug"),
-                block_network=block_network,
                 cloud_bucket_mounts=cloud_bucket_mounts_to_proto(cloud_bucket_mounts),
                 volume_mounts=volume_mounts,
                 pty_info=pty_info,
-                _experimental_scheduler=_experimental_scheduler,
-                _experimental_scheduler_placement=_experimental_scheduler_placement.proto
-                if _experimental_scheduler_placement
-                else None,
+                scheduler_placement=scheduler_placement.proto if scheduler_placement else None,
+                worker_id=config.get("worker_id"),
+                open_ports=api_pb2.PortSpecs(ports=open_ports),
+                network_access=network_access,
+                proxy_id=(proxy.object_id if proxy else None),
             )
 
-            create_req = api_pb2.SandboxCreateRequest(app_id=resolver.app_id, definition=definition)
+            # Note - `resolver.app_id` will be `None` for app-less sandboxes
+            create_req = api_pb2.SandboxCreateRequest(
+                app_id=resolver.app_id, definition=definition, environment_name=resolver.environment_name
+            )
             create_resp = await retry_transient_errors(resolver.client.stub.SandboxCreate, create_req)
 
             sandbox_id = create_resp.sandbox_id
@@ -317,15 +189,127 @@ class _Sandbox(_Object, type_prefix="sb"):
 
         return _Sandbox._from_loader(_load, "Sandbox()", deps=_deps)
 
+    @staticmethod
+    async def create(
+        *entrypoint_args: str,
+        app: Optional["modal.app._App"] = None,  # Optionally associate the sandbox with an app
+        environment_name: Optional[str] = None,  # Optionally override the default environment
+        image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
+        mounts: Sequence[_Mount] = (),  # Mounts to attach to the sandbox.
+        secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
+        network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
+        timeout: Optional[int] = None,  # Maximum execution time of the sandbox in seconds.
+        workdir: Optional[str] = None,  # Working directory of the sandbox.
+        gpu: GPU_T = None,
+        cloud: Optional[str] = None,
+        region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the sandbox on.
+        # Specify, in fractional CPU cores, how many CPU cores to request.
+        # Or, pass (request, limit) to additionally specify a hard limit in fractional CPU cores.
+        # CPU throttling will prevent a container from exceeding its specified limit.
+        cpu: Optional[Union[float, tuple[float, float]]] = None,
+        # Specify, in MiB, a memory request which is the minimum memory required.
+        # Or, pass (request, limit) to additionally specify a hard limit in MiB.
+        memory: Optional[Union[int, tuple[int, int]]] = None,
+        block_network: bool = False,  # Whether to block network access
+        # List of CIDRs the sandbox is allowed to access. If None, all CIDRs are allowed.
+        cidr_allowlist: Optional[Sequence[str]] = None,
+        volumes: dict[
+            Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]
+        ] = {},  # Mount points for Modal Volumes and CloudBucketMounts
+        pty_info: Optional[api_pb2.PTYInfo] = None,
+        # List of ports to tunnel into the sandbox. Encrypted ports are tunneled with TLS.
+        encrypted_ports: Sequence[int] = [],
+        # List of ports to tunnel into the sandbox without encryption.
+        unencrypted_ports: Sequence[int] = [],
+        # Reference to a Modal Proxy to use in front of this Sandbox.
+        proxy: Optional[_Proxy] = None,
+        _experimental_scheduler_placement: Optional[
+            SchedulerPlacement
+        ] = None,  # Experimental controls over fine-grained scheduling (alpha).
+        client: Optional[_Client] = None,
+    ) -> "_Sandbox":
+        from .app import _App
+
+        environment_name = _get_environment_name(environment_name)
+
+        # If there are no entrypoint args, we'll sleep forever so that the sandbox will stay
+        # alive long enough for the user to interact with it.
+        if len(entrypoint_args) == 0:
+            max_sleep_time = 60 * 60 * 24 * 2  # 2 days is plenty since workers roll every 24h
+            entrypoint_args = ("sleep", str(max_sleep_time))
+
+        # TODO(erikbern): Get rid of the `_new` method and create an already-hydrated object
+        obj = _Sandbox._new(
+            entrypoint_args,
+            image=image or _default_image,
+            mounts=mounts,
+            secrets=secrets,
+            timeout=timeout,
+            workdir=workdir,
+            gpu=gpu,
+            cloud=cloud,
+            region=region,
+            cpu=cpu,
+            memory=memory,
+            network_file_systems=network_file_systems,
+            block_network=block_network,
+            cidr_allowlist=cidr_allowlist,
+            volumes=volumes,
+            pty_info=pty_info,
+            encrypted_ports=encrypted_ports,
+            unencrypted_ports=unencrypted_ports,
+            proxy=proxy,
+            _experimental_scheduler_placement=_experimental_scheduler_placement,
+        )
+
+        app_id: Optional[str] = None
+        app_client: Optional[_Client] = None
+
+        if app is not None:
+            if app.app_id is None:
+                raise ValueError(
+                    "App has not been initialized yet. To create an App lazily, use `App.lookup`: \n"
+                    "app = modal.App.lookup('my-app', create_if_missing=True)\n"
+                    "modal.Sandbox.create('echo', 'hi', app=app)\n"
+                    "In order to initialize an existing `App` object, refer to our docs: https://modal.com/docs/guide/apps"
+                )
+
+            app_id = app.app_id
+            app_client = app._client
+        elif (container_app := _App._get_container_app()) is not None:
+            app_id = container_app.app_id
+            app_client = container_app._client
+        else:
+            arglist = ", ".join(repr(s) for s in entrypoint_args)
+            deprecation_error(
+                (2024, 9, 14),
+                "Creating a `Sandbox` without an `App` is deprecated.\n\n"
+                "You may pass in an `App` object, or reference one by name with `App.lookup`:\n\n"
+                "```\n"
+                "app = modal.App.lookup('sandbox-app', create_if_missing=True)\n"
+                f"sb = modal.Sandbox.create({arglist}, app=app)\n"
+                "```",
+            )
+
+        client = client or app_client or await _Client.from_env()
+
+        resolver = Resolver(client, environment_name=environment_name, app_id=app_id)
+        await resolver.load(obj)
+        return obj
+
     def _hydrate_metadata(self, handle_metadata: Optional[Message]):
-        self._stdout = LogsReader(api_pb2.FILE_DESCRIPTOR_STDOUT, self.object_id, self._client)
-        self._stderr = LogsReader(api_pb2.FILE_DESCRIPTOR_STDERR, self.object_id, self._client)
-        self._stdin = StreamWriter(self.object_id, self._client)
+        self._stdout: _StreamReader[str] = StreamReader[str](
+            api_pb2.FILE_DESCRIPTOR_STDOUT, self.object_id, "sandbox", self._client, by_line=True
+        )
+        self._stderr: _StreamReader[str] = StreamReader[str](
+            api_pb2.FILE_DESCRIPTOR_STDERR, self.object_id, "sandbox", self._client, by_line=True
+        )
+        self._stdin = StreamWriter(self.object_id, "sandbox", self._client)
         self._result = None
 
     @staticmethod
     async def from_id(sandbox_id: str, client: Optional[_Client] = None) -> "_Sandbox":
-        """Construct a Sandbox from an id and look up the sandbox result.
+        """Construct a Sandbox from an id and look up the Sandbox result.
 
         The ID of a Sandbox object can be accessed using `.object_id`.
         """
@@ -336,14 +320,57 @@ class _Sandbox(_Object, type_prefix="sb"):
         resp = await retry_transient_errors(client.stub.SandboxWait, req)
 
         obj = _Sandbox._new_hydrated(sandbox_id, client, None)
-        obj._result = resp.result
+
+        if resp.result.status:
+            obj._result = resp.result
 
         return obj
 
+    async def set_tags(self, tags: dict[str, str], *, client: Optional[_Client] = None):
+        """Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in `Sandbox.list`."""
+        environment_name = _get_environment_name()
+        if client is None:
+            client = await _Client.from_env()
+
+        tags_list = [api_pb2.SandboxTag(tag_name=name, tag_value=value) for name, value in tags.items()]
+
+        req = api_pb2.SandboxTagsSetRequest(
+            environment_name=environment_name,
+            sandbox_id=self.object_id,
+            tags=tags_list,
+        )
+        try:
+            await retry_transient_errors(client.stub.SandboxTagsSet, req)
+        except GRPCError as exc:
+            raise InvalidError(exc.message) if exc.status == Status.INVALID_ARGUMENT else exc
+
+    async def snapshot_filesystem(self, timeout: int = 55) -> _Image:
+        """Snapshot the filesystem of the Sandbox.
+
+        Returns an [`Image`](https://modal.com/docs/reference/modal.Image) object which
+        can be used to spawn a new Sandbox with the same filesystem.
+        """
+        req = api_pb2.SandboxSnapshotFsRequest(sandbox_id=self.object_id, timeout=timeout)
+        resp = await retry_transient_errors(self._client.stub.SandboxSnapshotFs, req)
+
+        if resp.result.status != api_pb2.GenericResult.GENERIC_STATUS_SUCCESS:
+            raise ExecutionError(resp.result.exception)
+
+        image_id = resp.image_id
+        metadata = resp.image_metadata
+
+        async def _load(self: _Image, resolver: Resolver, existing_object_id: Optional[str]):
+            self._hydrate(image_id, resolver.client, metadata)
+
+        rep = "Image()"
+        image = _Image._from_loader(_load, rep)
+
+        return image
+
     # Live handle methods
 
     async def wait(self, raise_on_termination: bool = True):
-        """Wait for the sandbox to finish running."""
+        """Wait for the Sandbox to finish running."""
 
         while True:
             req = api_pb2.SandboxWaitRequest(sandbox_id=self.object_id, timeout=50)
@@ -357,10 +384,37 @@ class _Sandbox(_Object, type_prefix="sb"):
                     raise SandboxTerminatedError()
                 break
 
+    async def tunnels(self, timeout: int = 50) -> dict[int, Tunnel]:
+        """Get tunnel metadata for the sandbox.
+
+        Raises `SandboxTimeoutError` if the tunnels are not available after the timeout.
+
+        Returns a dictionary of `Tunnel` objects which are keyed by the container port.
+
+        NOTE: Previous to client v0.64.152, this returned a list of `TunnelData` objects.
+        """
+
+        if self._tunnels:
+            return self._tunnels
+
+        req = api_pb2.SandboxGetTunnelsRequest(sandbox_id=self.object_id, timeout=timeout)
+        resp = await retry_transient_errors(self._client.stub.SandboxGetTunnels, req)
+
+        # If we couldn't get the tunnels in time, report the timeout.
+        if resp.result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
+            raise SandboxTimeoutError()
+
+        # Otherwise, we got the tunnels and can report the result.
+        self._tunnels = {
+            t.container_port: Tunnel(t.host, t.port, t.unencrypted_host, t.unencrypted_port) for t in resp.tunnels
+        }
+
+        return self._tunnels
+
     async def terminate(self):
-        """Terminate sandbox execution.
+        """Terminate Sandbox execution.
 
-        This is a no-op if the sandbox has already finished running."""
+        This is a no-op if the Sandbox has already finished running."""
 
         await retry_transient_errors(
             self._client.stub.SandboxTerminate, api_pb2.SandboxTerminateRequest(sandbox_id=self.object_id)
@@ -368,9 +422,9 @@ class _Sandbox(_Object, type_prefix="sb"):
         await self.wait(raise_on_termination=False)
 
     async def poll(self) -> Optional[int]:
-        """Check if the sandbox has finished running.
+        """Check if the Sandbox has finished running.
 
-        Returns `None` if the sandbox is still running, else returns the exit code.
+        Returns `None` if the Sandbox is still running, else returns the exit code.
         """
 
         req = api_pb2.SandboxWaitRequest(sandbox_id=self.object_id, timeout=0)
@@ -381,21 +435,186 @@ class _Sandbox(_Object, type_prefix="sb"):
 
         return self.returncode
 
+    async def _get_task_id(self):
+        while not self._task_id:
+            resp = await self._client.stub.SandboxGetTaskId(api_pb2.SandboxGetTaskIdRequest(sandbox_id=self.object_id))
+            self._task_id = resp.task_id
+            if not self._task_id:
+                await asyncio.sleep(0.5)
+        return self._task_id
+
+    @overload
+    async def exec(
+        self,
+        *cmds: str,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
+        stdout: StreamType = StreamType.PIPE,
+        stderr: StreamType = StreamType.PIPE,
+        timeout: Optional[int] = None,
+        workdir: Optional[str] = None,
+        secrets: Sequence[_Secret] = (),
+        text: Literal[True] = True,
+        bufsize: Literal[-1, 1] = -1,
+        _pty_info: Optional[api_pb2.PTYInfo] = None,
+    ) -> _ContainerProcess[str]:
+        ...
+
+    @overload
+    async def exec(
+        self,
+        *cmds: str,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
+        stdout: StreamType = StreamType.PIPE,
+        stderr: StreamType = StreamType.PIPE,
+        timeout: Optional[int] = None,
+        workdir: Optional[str] = None,
+        secrets: Sequence[_Secret] = (),
+        text: Literal[False] = False,
+        bufsize: Literal[-1, 1] = -1,
+        _pty_info: Optional[api_pb2.PTYInfo] = None,
+    ) -> _ContainerProcess[bytes]:
+        ...
+
+    async def exec(
+        self,
+        *cmds: str,
+        pty_info: Optional[api_pb2.PTYInfo] = None,  # Deprecated: internal use only
+        stdout: StreamType = StreamType.PIPE,
+        stderr: StreamType = StreamType.PIPE,
+        timeout: Optional[int] = None,
+        workdir: Optional[str] = None,
+        secrets: Sequence[_Secret] = (),
+        # Encode output as text.
+        text: bool = True,
+        # Control line-buffered output.
+        # -1 means unbuffered, 1 means line-buffered (only available if `text=True`).
+        bufsize: Literal[-1, 1] = -1,
+        # Internal option to set terminal size and metadata
+        _pty_info: Optional[api_pb2.PTYInfo] = None,
+    ):
+        """Execute a command in the Sandbox and return
+        a [`ContainerProcess`](/docs/reference/modal.ContainerProcess#modalcontainer_process) handle.
+
+        **Usage**
+
+        ```python
+        app = modal.App.lookup("my-app", create_if_missing=True)
+
+        sandbox = modal.Sandbox.create("sleep", "infinity", app=app)
+
+        process = sandbox.exec("bash", "-c", "for i in $(seq 1 10); do echo foo $i; sleep 0.5; done")
+
+        for line in process.stdout:
+            print(line)
+        ```
+        """
+
+        if workdir is not None and not workdir.startswith("/"):
+            raise InvalidError(f"workdir must be an absolute path, got: {workdir}")
+
+        # Force secret resolution so we can pass the secret IDs to the backend.
+        for secret in secrets:
+            await secret.resolve(client=self._client)
+
+        task_id = await self._get_task_id()
+        req = api_pb2.ContainerExecRequest(
+            task_id=task_id,
+            command=cmds,
+            pty_info=_pty_info or pty_info,
+            runtime_debug=config.get("function_runtime_debug"),
+            timeout_secs=timeout or 0,
+            workdir=workdir,
+            secret_ids=[secret.object_id for secret in secrets],
+        )
+        resp = await retry_transient_errors(self._client.stub.ContainerExec, req)
+        by_line = bufsize == 1
+        return _ContainerProcess(resp.exec_id, self._client, stdout=stdout, stderr=stderr, text=text, by_line=by_line)
+
+    @overload
+    async def open(
+        self,
+        path: str,
+        mode: "_typeshed.OpenTextMode",
+    ) -> _FileIO[str]:
+        ...
+
+    @overload
+    async def open(
+        self,
+        path: str,
+        mode: "_typeshed.OpenBinaryMode",
+    ) -> _FileIO[bytes]:
+        ...
+
+    async def open(
+        self,
+        path: str,
+        mode: Union["_typeshed.OpenTextMode", "_typeshed.OpenBinaryMode"] = "r",
+    ):
+        """Open a file in the Sandbox and return
+        a [`FileIO`](/docs/reference/modal.FileIO#modalfile_io) handle.
+
+        **Usage**
+
+        ```python notest
+        sb = modal.Sandbox.create(app=sb_app)
+        f = sb.open("/test.txt", "w")
+        f.write("hello")
+        f.close()
+        ```
+        """
+        task_id = await self._get_task_id()
+        return await _FileIO.create(path, mode, self._client, task_id)
+
+    async def ls(self, path: str) -> list[str]:
+        """List the contents of a directory in the Sandbox."""
+        task_id = await self._get_task_id()
+        return await _FileIO.ls(path, self._client, task_id)
+
+    async def mkdir(self, path: str, parents: bool = False) -> None:
+        """Create a new directory in the Sandbox."""
+        task_id = await self._get_task_id()
+        return await _FileIO.mkdir(path, self._client, task_id, parents)
+
+    async def rm(self, path: str, recursive: bool = False) -> None:
+        """Remove a file or directory in the Sandbox."""
+        task_id = await self._get_task_id()
+        return await _FileIO.rm(path, self._client, task_id, recursive)
+
+    async def watch(
+        self,
+        path: str,
+        filter: Optional[list[FileWatchEventType]] = None,
+        recursive: Optional[bool] = None,
+        timeout: Optional[int] = None,
+    ) -> AsyncIterator[FileWatchEvent]:
+        task_id = await self._get_task_id()
+        async for event in _FileIO.watch(path, self._client, task_id, filter, recursive, timeout):
+            yield event
+
     @property
-    def stdout(self) -> _LogsReader:
-        """`LogsReader` for the sandbox's stdout stream."""
+    def stdout(self) -> _StreamReader[str]:
+        """
+        [`StreamReader`](/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the sandbox's stdout stream.
+        """
 
         return self._stdout
 
     @property
-    def stderr(self) -> _LogsReader:
-        """`LogsReader` for the sandbox's stderr stream."""
+    def stderr(self) -> _StreamReader[str]:
+        """[`StreamReader`](/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the sandbox's stderr stream.
+        """
 
         return self._stderr
 
     @property
     def stdin(self) -> _StreamWriter:
-        """`StreamWriter` for the sandbox's stdin stream."""
+        """
+        [`StreamWriter`](/docs/reference/modal.io_streams#modalio_streamsstreamwriter) for
+        the sandbox's stdin stream.
+        """
 
         return self._stdin
 
@@ -414,5 +633,64 @@ class _Sandbox(_Object, type_prefix="sb"):
         else:
             return self._result.exitcode
 
+    @staticmethod
+    async def list(
+        *, app_id: Optional[str] = None, tags: Optional[dict[str, str]] = None, client: Optional[_Client] = None
+    ) -> AsyncGenerator["_Sandbox", None]:
+        """List all sandboxes for the current environment or app ID (if specified). If tags are specified, only
+        sandboxes that have at least those tags are returned. Returns an iterator over `Sandbox` objects."""
+        before_timestamp = None
+        environment_name = _get_environment_name()
+        if client is None:
+            client = await _Client.from_env()
+
+        tags_list = [api_pb2.SandboxTag(tag_name=name, tag_value=value) for name, value in tags.items()] if tags else []
+
+        while True:
+            req = api_pb2.SandboxListRequest(
+                app_id=app_id,
+                before_timestamp=before_timestamp,
+                environment_name=environment_name,
+                include_finished=False,
+                tags=tags_list,
+            )
+
+            # Fetches a batch of sandboxes.
+            try:
+                resp = await retry_transient_errors(client.stub.SandboxList, req)
+            except GRPCError as exc:
+                raise InvalidError(exc.message) if exc.status == Status.INVALID_ARGUMENT else exc
+
+            if not resp.sandboxes:
+                return
+
+            for sandbox_info in resp.sandboxes:
+                obj = _Sandbox._new_hydrated(sandbox_info.id, client, None)
+                obj._result = sandbox_info.task_info.result
+                yield obj
+
+            # Fetch the next batch starting from the end of the current one.
+            before_timestamp = resp.sandboxes[-1].created_at
+
 
 Sandbox = synchronize_api(_Sandbox)
+
+
+def __getattr__(name):
+    if name == "LogsReader":
+        deprecation_error(
+            (2024, 8, 12),
+            "`modal.sandbox.LogsReader` is deprecated. Please import `modal.io_streams.StreamReader` instead.",
+        )
+        from .io_streams import StreamReader
+
+        return StreamReader
+    elif name == "StreamWriter":
+        deprecation_error(
+            (2024, 8, 12),
+            "`modal.sandbox.StreamWriter` is deprecated. Please import `modal.io_streams.StreamWriter` instead.",
+        )
+        from .io_streams import StreamWriter
+
+        return StreamWriter
+    raise AttributeError(f"module {__name__} has no attribute {name}")