modal 1.1.5.dev19__py3-none-any.whl → 1.1.5.dev21__py3-none-any.whl

modal/image.pyi

@@ -166,7 +166,7 @@ class _Image(modal._object._Object):
                 [typing.Literal["2023.12", "2024.04", "2024.10", "2025.06", "PREVIEW"]], DockerfileSpec
             ]
         ] = None,
-        secrets: typing.Optional[collections.abc.Sequence[modal.secret._Secret]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu_config: typing.Optional[modal_proto.api_pb2.GPUConfig] = None,
         build_function: typing.Optional[modal._functions._Function] = None,
         build_function_input: typing.Optional[modal_proto.api_pb2.FunctionInput] = None,
@@ -327,7 +327,8 @@ class _Image(modal._object._Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install a list of Python packages using pip.
@@ -369,7 +370,8 @@ class _Image(modal._object._Object):
         pre: bool = False,
         extra_options: str = "",
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         force_build: bool = False,
     ) -> _Image:
         """Install a list of Python packages from private git repositories using pip.
@@ -414,7 +416,8 @@ class _Image(modal._object._Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install a list of Python packages from a local `requirements.txt` file."""
@@ -431,7 +434,8 @@ class _Image(modal._object._Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install dependencies specified by a local `pyproject.toml` file.
@@ -454,7 +458,8 @@ class _Image(modal._object._Object):
         extra_options: str = "",
         force_build: bool = False,
         uv_version: typing.Optional[str] = None,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install a list of Python packages using uv pip install.
@@ -487,7 +492,8 @@ class _Image(modal._object._Object):
         only: list[str] = [],
         poetry_version: typing.Optional[str] = "latest",
         old_installer: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install poetry *dependencies* specified by a local `pyproject.toml` file.
@@ -514,7 +520,8 @@ class _Image(modal._object._Object):
         frozen: bool = True,
         extra_options: str = "",
         uv_version: typing.Optional[str] = None,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Creates a virtual environment with the dependencies in a uv managed project with `uv sync`.
@@ -535,7 +542,8 @@ class _Image(modal._object._Object):
         self,
         *dockerfile_commands: typing.Union[str, list[str]],
         context_files: dict[str, str] = {},
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         context_mount: typing.Optional[modal.mount._Mount] = None,
         context_dir: typing.Union[str, pathlib.Path, None] = None,
@@ -597,7 +605,8 @@ class _Image(modal._object._Object):
     def run_commands(
         self,
         *commands: typing.Union[str, list[str]],
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
     ) -> _Image:
@@ -615,7 +624,8 @@ class _Image(modal._object._Object):
         spec_file: typing.Optional[str] = None,
         channels: list[str] = [],
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install a list of additional packages using micromamba."""
@@ -756,7 +766,8 @@ class _Image(modal._object._Object):
         context_mount: typing.Optional[modal.mount._Mount] = None,
         force_build: bool = False,
         context_dir: typing.Union[str, pathlib.Path, None] = None,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         add_python: typing.Optional[str] = None,
         build_args: dict[str, str] = {},
@@ -824,7 +835,8 @@ class _Image(modal._object._Object):
         self,
         *packages: typing.Union[str, list[str]],
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> _Image:
         """Install a list of Debian packages using `apt`.
@@ -841,7 +853,8 @@ class _Image(modal._object._Object):
         self,
         raw_f: collections.abc.Callable[..., typing.Any],
         *,
-        secrets: collections.abc.Sequence[modal.secret._Secret] = (),
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
         volumes: dict[
             typing.Union[str, pathlib.PurePosixPath],
             typing.Union[modal.volume._Volume, modal.cloud_bucket_mount._CloudBucketMount],
@@ -1008,7 +1021,7 @@ class Image(modal.object.Object):
                 [typing.Literal["2023.12", "2024.04", "2024.10", "2025.06", "PREVIEW"]], DockerfileSpec
             ]
         ] = None,
-        secrets: typing.Optional[collections.abc.Sequence[modal.secret.Secret]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu_config: typing.Optional[modal_proto.api_pb2.GPUConfig] = None,
         build_function: typing.Optional[modal.functions.Function] = None,
         build_function_input: typing.Optional[modal_proto.api_pb2.FunctionInput] = None,
@@ -1178,7 +1191,8 @@ class Image(modal.object.Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install a list of Python packages using pip.
@@ -1220,7 +1234,8 @@ class Image(modal.object.Object):
         pre: bool = False,
         extra_options: str = "",
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         force_build: bool = False,
     ) -> Image:
         """Install a list of Python packages from private git repositories using pip.
@@ -1265,7 +1280,8 @@ class Image(modal.object.Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install a list of Python packages from a local `requirements.txt` file."""
@@ -1282,7 +1298,8 @@ class Image(modal.object.Object):
         pre: bool = False,
         extra_options: str = "",
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install dependencies specified by a local `pyproject.toml` file.
@@ -1305,7 +1322,8 @@ class Image(modal.object.Object):
         extra_options: str = "",
         force_build: bool = False,
         uv_version: typing.Optional[str] = None,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install a list of Python packages using uv pip install.
@@ -1338,7 +1356,8 @@ class Image(modal.object.Object):
         only: list[str] = [],
         poetry_version: typing.Optional[str] = "latest",
         old_installer: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install poetry *dependencies* specified by a local `pyproject.toml` file.
@@ -1365,7 +1384,8 @@ class Image(modal.object.Object):
         frozen: bool = True,
         extra_options: str = "",
         uv_version: typing.Optional[str] = None,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Creates a virtual environment with the dependencies in a uv managed project with `uv sync`.
@@ -1386,7 +1406,8 @@ class Image(modal.object.Object):
         self,
         *dockerfile_commands: typing.Union[str, list[str]],
         context_files: dict[str, str] = {},
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         context_mount: typing.Optional[modal.mount.Mount] = None,
         context_dir: typing.Union[str, pathlib.Path, None] = None,
@@ -1448,7 +1469,8 @@ class Image(modal.object.Object):
     def run_commands(
         self,
         *commands: typing.Union[str, list[str]],
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
     ) -> Image:
@@ -1466,7 +1488,8 @@ class Image(modal.object.Object):
         spec_file: typing.Optional[str] = None,
         channels: list[str] = [],
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install a list of additional packages using micromamba."""
@@ -1607,7 +1630,8 @@ class Image(modal.object.Object):
         context_mount: typing.Optional[modal.mount.Mount] = None,
         force_build: bool = False,
         context_dir: typing.Union[str, pathlib.Path, None] = None,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         add_python: typing.Optional[str] = None,
         build_args: dict[str, str] = {},
@@ -1675,7 +1699,8 @@ class Image(modal.object.Object):
         self,
         *packages: typing.Union[str, list[str]],
         force_build: bool = False,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = [],
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
     ) -> Image:
         """Install a list of Debian packages using `apt`.
@@ -1692,7 +1717,8 @@ class Image(modal.object.Object):
         self,
         raw_f: collections.abc.Callable[..., typing.Any],
         *,
-        secrets: collections.abc.Sequence[modal.secret.Secret] = (),
+        env: typing.Optional[dict[str, typing.Optional[str]]] = None,
+        secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
         volumes: dict[
             typing.Union[str, pathlib.PurePosixPath],
             typing.Union[modal.volume.Volume, modal.cloud_bucket_mount.CloudBucketMount],

modal/runner.py

@@ -607,12 +607,12 @@ async def _interactive_shell(
 
         try:
             if pty:
-                container_process = await sandbox.exec(
+                container_process = await sandbox._exec(
                     *sandbox_cmds, pty_info=get_pty_info(shell=True) if pty else None
                 )
                 await container_process.attach()
             else:
-                container_process = await sandbox.exec(
+                container_process = await sandbox._exec(
                     *sandbox_cmds, stdout=StreamType.STDOUT, stderr=StreamType.STDOUT
                 )
                 await container_process.wait()

modal/sandbox.py

@@ -3,10 +3,11 @@ import asyncio
 import json
 import os
 import time
-from collections.abc import AsyncGenerator, Sequence
+from collections.abc import AsyncGenerator, Collection, Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, AsyncIterator, Literal, Optional, Union, overload
 
+from ._pty import get_pty_info
 from .config import config, logger
 
 if TYPE_CHECKING:
@@ -124,11 +125,15 @@ class _Sandbox(_Object, type_prefix="sb"):
     _tunnels: Optional[dict[int, Tunnel]] = None
     _enable_snapshot: bool = False
 
+    @staticmethod
+    def _default_pty_info() -> api_pb2.PTYInfo:
+        return get_pty_info(shell=True, no_terminate_on_idle_stdin=True)
+
     @staticmethod
     def _new(
         args: Sequence[str],
         image: _Image,
-        secrets: Sequence[_Secret],
+        secrets: Collection[_Secret],
         name: Optional[str] = None,
         timeout: int = 300,
         idle_timeout: Optional[int] = None,
@@ -143,7 +148,8 @@ class _Sandbox(_Object, type_prefix="sb"):
         block_network: bool = False,
         cidr_allowlist: Optional[Sequence[str]] = None,
         volumes: dict[Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]] = {},
-        pty_info: Optional[api_pb2.PTYInfo] = None,
+        pty: bool = False,
+        pty_info: Optional[api_pb2.PTYInfo] = None,  # deprecated
         encrypted_ports: Sequence[int] = [],
         h2_ports: Sequence[int] = [],
         unencrypted_ports: Sequence[int] = [],
@@ -177,6 +183,9 @@ class _Sandbox(_Object, type_prefix="sb"):
         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)]
 
+        if pty:
+            pty_info = _Sandbox._default_pty_info()
+
         def _deps() -> list[_Object]:
             deps: list[_Object] = [image] + list(mounts) + list(secrets)
             for _, vol in validated_network_file_systems:
@@ -279,7 +288,8 @@ class _Sandbox(_Object, type_prefix="sb"):
         app: Optional["modal.app._App"] = None,
         name: Optional[str] = None,  # Optionally give the sandbox a name. Unique within an app.
         image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
-        secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
+        env: Optional[dict[str, Optional[str]]] = None,  # Environment variables to set in the Sandbox.
+        secrets: Optional[Collection[_Secret]] = None,  # Secrets to inject into the Sandbox as environment variables.
         network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
         timeout: int = 300,  # Maximum lifetime of the sandbox in seconds.
         # The amount of time in seconds that a sandbox can be idle before being terminated.
@@ -301,7 +311,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         volumes: dict[
             Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]
         ] = {},  # Mount points for Modal Volumes and CloudBucketMounts
-        pty_info: Optional[api_pb2.PTYInfo] = None,
+        pty: bool = False,  # Enable a PTY for the Sandbox
         # List of ports to tunnel into the sandbox. Encrypted ports are tunneled with TLS.
         encrypted_ports: Sequence[int] = [],
         # List of encrypted ports to tunnel into the sandbox, using HTTP/2.
@@ -320,6 +330,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         ] = None,  # Experimental controls over fine-grained scheduling (alpha).
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,  # *DEPRECATED* Optionally override the default environment
+        pty_info: Optional[api_pb2.PTYInfo] = None,  # *DEPRECATED* Use `pty` instead. `pty` will override `pty_info`.
     ) -> "_Sandbox":
         """
         Create a new Sandbox to run untrusted, arbitrary code.
@@ -342,6 +353,17 @@ class _Sandbox(_Object, type_prefix="sb"):
                 "A sandbox's environment is determined by the app it is associated with.",
             )
 
+        if pty_info is not None:
+            deprecation_warning(
+                (2025, 9, 12),
+                "The `pty_info` parameter is deprecated and will be removed in a future release. "
+                "Set the `pty` parameter to `True` instead.",
+            )
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         return await _Sandbox._create(
             *args,
             app=app,
@@ -360,7 +382,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             block_network=block_network,
             cidr_allowlist=cidr_allowlist,
             volumes=volumes,
-            pty_info=pty_info,
+            pty=pty,
             encrypted_ports=encrypted_ports,
             h2_ports=h2_ports,
             unencrypted_ports=unencrypted_ports,
@@ -370,59 +392,48 @@ class _Sandbox(_Object, type_prefix="sb"):
             _experimental_scheduler_placement=_experimental_scheduler_placement,
             client=client,
             verbose=verbose,
+            pty_info=pty_info,
         )
 
     @staticmethod
     async def _create(
-        *args: str,  # Set the CMD of the Sandbox, overriding any CMD of the container image.
-        # Associate the sandbox with an app. Required unless creating from a container.
+        *args: str,
         app: Optional["modal.app._App"] = None,
-        name: Optional[str] = None,  # Optionally give the sandbox a name. Unique within an app.
-        image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
-        secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
+        name: Optional[str] = None,
+        image: Optional[_Image] = None,
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         mounts: Sequence[_Mount] = (),
         network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
-        timeout: int = 300,  # Maximum lifetime of the sandbox in seconds.
-        # The amount of time in seconds that a sandbox can be idle before being terminated.
+        timeout: int = 300,
         idle_timeout: Optional[int] = None,
-        workdir: Optional[str] = None,  # Working directory of the sandbox.
+        workdir: Optional[str] = None,
         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.
+        region: Optional[Union[str, Sequence[str]]] = None,
         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.
+        block_network: bool = False,
         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.
+        volumes: dict[Union[str, os.PathLike], Union[_Volume, _CloudBucketMount]] = {},
+        pty: bool = False,
         encrypted_ports: Sequence[int] = [],
-        # List of encrypted ports to tunnel into the sandbox, using HTTP/2.
         h2_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_options: Optional[dict[str, bool]] = None,
-        # Enable memory snapshots.
         _experimental_enable_snapshot: bool = False,
-        _experimental_scheduler_placement: Optional[
-            SchedulerPlacement
-        ] = None,  # Experimental controls over fine-grained scheduling (alpha).
+        _experimental_scheduler_placement: Optional[SchedulerPlacement] = None,
         client: Optional[_Client] = None,
         verbose: bool = False,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
     ):
-        # This method exposes some internal arguments (currently `mounts`) which are not in the public API
-        # `mounts` is currently only used by modal shell (cli) to provide a function's mounts to the
-        # sandbox that runs the shell session
+        """Private method used internally.
+
+        This method exposes some internal arguments (currently `mounts`) which are not in the public API.
+        `mounts` is currently only used by modal shell (cli) to provide a function's mounts to the
+        sandbox that runs the shell session.
+        """
         from .app import _App
 
         _validate_exec_args(args)
@@ -432,6 +443,10 @@ class _Sandbox(_Object, type_prefix="sb"):
         if block_network and (encrypted_ports or h2_ports or unencrypted_ports):
             raise InvalidError("Cannot specify open ports when `block_network` is enabled")
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         # TODO(erikbern): Get rid of the `_new` method and create an already-hydrated object
         obj = _Sandbox._new(
             args,
@@ -451,6 +466,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             block_network=block_network,
             cidr_allowlist=cidr_allowlist,
             volumes=volumes,
+            pty=pty,
             pty_info=pty_info,
             encrypted_ports=encrypted_ports,
             h2_ports=h2_ports,
@@ -703,14 +719,16 @@ class _Sandbox(_Object, type_prefix="sb"):
     async def exec(
         self,
         *args: 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] = (),
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         text: Literal[True] = True,
         bufsize: Literal[-1, 1] = -1,
+        pty: bool = False,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
         _pty_info: Optional[api_pb2.PTYInfo] = None,
     ) -> _ContainerProcess[str]: ...
 
@@ -718,33 +736,38 @@ class _Sandbox(_Object, type_prefix="sb"):
     async def exec(
         self,
         *args: 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] = (),
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         text: Literal[False] = False,
         bufsize: Literal[-1, 1] = -1,
+        pty: bool = False,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
         _pty_info: Optional[api_pb2.PTYInfo] = None,
     ) -> _ContainerProcess[bytes]: ...
 
     async def exec(
         self,
         *args: 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] = (),
+        env: Optional[dict[str, Optional[str]]] = None,  # Environment variables to set during command execution.
+        secrets: Optional[
+            Collection[_Secret]
+        ] = None,  # Secrets to inject as environment variables during command execution.
         # 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,
+        pty: bool = False,  # Enable a PTY for the command
+        _pty_info: Optional[api_pb2.PTYInfo] = None,  # *DEPRECATED* Use `pty` instead. `pty` will override `pty_info`.
+        pty_info: Optional[api_pb2.PTYInfo] = None,  # *DEPRECATED* Use `pty` instead. `pty` will override `pty_info`.
     ):
         """Execute a command in the Sandbox and return a ContainerProcess handle.
 
@@ -764,11 +787,54 @@ class _Sandbox(_Object, type_prefix="sb"):
             print(line)
         ```
         """
+        if pty_info is not None or _pty_info is not None:
+            deprecation_warning(
+                (2025, 9, 12),
+                "The `_pty_info` and `pty_info` parameters are deprecated and will be removed in a future release. "
+                "Set the `pty` parameter to `True` instead.",
+            )
+        pty_info = _pty_info or pty_info
+        if pty:
+            pty_info = self._default_pty_info()
+
+        return await self._exec(
+            *args,
+            pty_info=pty_info,
+            stdout=stdout,
+            stderr=stderr,
+            timeout=timeout,
+            workdir=workdir,
+            env=env,
+            secrets=secrets,
+            text=text,
+            bufsize=bufsize,
+        )
+
+    async def _exec(
+        self,
+        *args: str,
+        pty_info: Optional[api_pb2.PTYInfo] = None,
+        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,
+    ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
+        """Private method used internally.
 
+        This method exposes some internal arguments (currently `pty_info`) which are not in the public API.
+        """
         if workdir is not None and not workdir.startswith("/"):
             raise InvalidError(f"workdir must be an absolute path, got: {workdir}")
         _validate_exec_args(args)
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         # Force secret resolution so we can pass the secret IDs to the backend.
         secret_coros = [secret.hydrate(client=self._client) for secret in secrets]
         await TaskContext.gather(*secret_coros)
@@ -777,7 +843,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         req = api_pb2.ContainerExecRequest(
             task_id=task_id,
             command=args,
-            pty_info=_pty_info or pty_info,
+            pty_info=pty_info,
             runtime_debug=config.get("function_runtime_debug"),
             timeout_secs=timeout or 0,
             workdir=workdir,