modal 1.5.2.dev20__tar.gz → 1.5.2.dev21__tar.gz

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/PKG-INFO

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

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/cli/container.py

@@ -269,15 +269,23 @@ async def _exec_impl(
     pty: bool | None = None,
     container_id: str = "",
     command: tuple[str, ...] = (),
+    object_id_for_v2: str | None = None,
 ):
-    """Execute a command in a container (implementation)."""
+    """Execute a command in a container (implementation).
+
+    For tasks belonging to V2 sandboxes, `object_id_for_v2` must be set to the
+    sandbox ID.
+    """
 
     if pty is None:
         pty = is_tty()
 
     client = await _Client.from_env()
 
-    command_router_client = await TaskCommandRouterClient.init(client, container_id)
+    if object_id_for_v2 is not None:
+        command_router_client = await TaskCommandRouterClient.init_v2(client, object_id_for_v2, container_id)
+    else:
+        command_router_client = await TaskCommandRouterClient.init(client, container_id)
 
     process_id = str(uuid.uuid4())
 

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/cli/curl.py

@@ -117,10 +117,12 @@ async def curl(curl_args: tuple[str, ...]):
     All arguments are passed directly to `curl`, which must be installed locally.
 
     Examples:
-        ```bash
-        modal curl https://user--my-app.us-west.modal.direct
-        modal curl -X GET https://user--my-app.us-west.modal.direct
-        ```
+
+    ```bash
+    modal curl https://user--my-app.us-west.modal.direct
+    modal curl -X GET https://user--my-app.us-west.modal.direct
+    ```
+
     """
     url = find_url(curl_args)
     if url is None:

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/cli/shell.py

@@ -17,7 +17,7 @@ from ..functions import Function
 from ..image import Image
 from ..mount import _Mount
 from ..runner import interactive_shell
-from ..sandbox import _MAIN_CONTAINER_NAME, Sandbox
+from ..sandbox import _MAIN_CONTAINER_NAME, Sandbox, _is_v2_sandbox_id
 from ..secret import Secret
 from ..stream_type import StreamType
 from ..volume import Volume
@@ -135,6 +135,8 @@ def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
     if container_name is not None and container_name != _MAIN_CONTAINER_NAME:
         return _start_shell_in_sidecar_container(sandbox_id, container_name, cmd, pty)
 
+    object_id_for_v2: str | None = None
+
     if _is_valid_modal_id(sandbox_id, "sb-"):
         try:
             sandbox = Sandbox.from_id(sandbox_id)
@@ -143,10 +145,12 @@ def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
             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)}")
+        if _is_v2_sandbox_id(sandbox_id):
+            object_id_for_v2 = sandbox_id
 
     assert _is_valid_modal_id(ref, "ta-")
     try:
-        _exec_impl(container_id=ref, command=shlex.split(cmd), pty=pty)
+        _exec_impl(container_id=ref, command=shlex.split(cmd), pty=pty, object_id_for_v2=object_id_for_v2)
     except NotFoundError:
         raise ClickException(f"Container '{ref}' not found (is it still running?)")
     except Exception as e:

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/client.pyi

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

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/sandbox.py

@@ -861,9 +861,10 @@ class _Sandbox(_Object, type_prefix="sb"):
         (e.g. `region="us-east-1"`).
 
         V2 sandboxes created with this method are not currently returned by
-        `Sandbox.list()` and cannot be looked up with `Sandbox.from_name()`.
-        Store `sandbox.object_id` if you need to retrieve the sandbox later, and
-        use `Sandbox.from_id(sandbox.object_id)` to reattach.
+        `Sandbox.list()`. A named sandbox can be looked up with
+        `Sandbox._experimental_from_name(app_name, name)`; otherwise store
+        `sandbox.object_id` and use `Sandbox.from_id(sandbox.object_id)` to
+        reattach.
         """
         from .app import _App
 
@@ -1186,6 +1187,44 @@ class _Sandbox(_Object, type_prefix="sb"):
         resp = await client.stub.SandboxGetFromName(req)
         return _Sandbox._new_hydrated(resp.sandbox_id, client, None)
 
+    @staticmethod
+    async def _experimental_from_name(
+        app_name: str,
+        name: str,
+        *,
+        environment_name: str | None = None,
+        client: _Client | None = None,
+    ) -> "_Sandbox":
+        """Get a running V2 Sandbox by name from a deployed App.
+
+        This looks up V2 sandboxes, ie sandboxes created via `modal.Sandbox._experimental_create`.
+
+        Args:
+            app_name: Name of the deployed app to look up the sandbox under.
+            name: Sandbox name to resolve.
+            environment_name: Optional environment name for the lookup; defaults to the configured environment.
+            client: Modal client to use for the RPC; defaults to `Client.from_env()` when omitted.
+
+        Returns:
+            A `Sandbox` handle for the running sandbox.
+
+        Raises:
+            NotFoundError: If no running sandbox exists with the given name.
+        """
+        if client is None:
+            client = await _Client.from_env()
+        env_name = _get_environment_name(environment_name)
+
+        req = api_pb2.SandboxGetFromNameRequest(sandbox_name=name, app_name=app_name, environment_name=env_name)
+        assert client._auth_token_manager
+        auth_token = await client._auth_token_manager.get_token()
+        resp = await client.stub.SandboxGetFromNameV2(req, metadata=[("x-modal-auth-token", auth_token)])
+
+        obj = _Sandbox._new_hydrated(resp.sandbox_id, client, None)
+        obj._is_v2 = True
+        obj._hydrate_metadata_v2()
+        return obj
+
     @staticmethod
     async def from_id(sandbox_id: str, client: _Client | None = None) -> "_Sandbox":
         """Construct a Sandbox from an id and look up the Sandbox result.
@@ -2279,15 +2318,15 @@ class _Sandbox(_Object, type_prefix="sb"):
 
     @staticmethod
     async def _experimental_list(
-        *, app_id: str | None = None, client: _Client | None = None
+        *, app_id: str | None = None, tags: dict[str, str] | None = None, client: _Client | None = None
     ) -> AsyncGenerator["_Sandbox", None]:
         """List v2 Sandboxes in an App.
 
         This function lists v2 sandboxes, ie sandboxes created via modal.Sandbox._experimental_create.
-        Filtering based on tags is not yet supported.
 
         Args:
             app_id: The App to list Sandboxes under.
+            tags: If set, only sandboxes containing at least these tags are returned.
             client: Optional client to use for the session.
 
         Yields:
@@ -2304,12 +2343,15 @@ class _Sandbox(_Object, type_prefix="sb"):
         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 []
+
         assert client._auth_token_manager
         while True:
             req = api_pb2.SandboxListRequest(
                 app_id=app_id,
                 before_timestamp=before_timestamp,
                 include_finished=False,
+                tags=tags_list,
             )
 
             # Fetches a batch of sandboxes. SandboxListV2 authenticates via the

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/sandbox.pyi

@@ -409,9 +409,10 @@ class _Sandbox(modal._object._Object):
         (e.g. `region="us-east-1"`).
 
         V2 sandboxes created with this method are not currently returned by
-        `Sandbox.list()` and cannot be looked up with `Sandbox.from_name()`.
-        Store `sandbox.object_id` if you need to retrieve the sandbox later, and
-        use `Sandbox.from_id(sandbox.object_id)` to reattach.
+        `Sandbox.list()`. A named sandbox can be looked up with
+        `Sandbox._experimental_from_name(app_name, name)`; otherwise store
+        `sandbox.object_id` and use `Sandbox.from_id(sandbox.object_id)` to
+        reattach.
         """
         ...
 
@@ -465,6 +466,32 @@ class _Sandbox(modal._object._Object):
         """
         ...
 
+    @staticmethod
+    async def _experimental_from_name(
+        app_name: str,
+        name: str,
+        *,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> _Sandbox:
+        """Get a running V2 Sandbox by name from a deployed App.
+
+        This looks up V2 sandboxes, ie sandboxes created via `modal.Sandbox._experimental_create`.
+
+        Args:
+            app_name: Name of the deployed app to look up the sandbox under.
+            name: Sandbox name to resolve.
+            environment_name: Optional environment name for the lookup; defaults to the configured environment.
+            client: Modal client to use for the RPC; defaults to `Client.from_env()` when omitted.
+
+        Returns:
+            A `Sandbox` handle for the running sandbox.
+
+        Raises:
+            NotFoundError: If no running sandbox exists with the given name.
+        """
+        ...
+
     @staticmethod
     async def from_id(sandbox_id: str, client: typing.Optional[modal.client._Client] = None) -> _Sandbox:
         """Construct a Sandbox from an id and look up the Sandbox result.
@@ -922,15 +949,18 @@ class _Sandbox(modal._object._Object):
 
     @staticmethod
     def _experimental_list(
-        *, app_id: typing.Optional[str] = None, client: typing.Optional[modal.client._Client] = None
+        *,
+        app_id: typing.Optional[str] = None,
+        tags: typing.Optional[dict[str, str]] = None,
+        client: typing.Optional[modal.client._Client] = None,
     ) -> collections.abc.AsyncGenerator[_Sandbox, None]:
         """List v2 Sandboxes in an App.
 
         This function lists v2 sandboxes, ie sandboxes created via modal.Sandbox._experimental_create.
-        Filtering based on tags is not yet supported.
 
         Args:
             app_id: The App to list Sandboxes under.
+            tags: If set, only sandboxes containing at least these tags are returned.
             client: Optional client to use for the session.
 
         Yields:
@@ -1729,9 +1759,10 @@ class Sandbox(modal.object.Object):
             (e.g. `region="us-east-1"`).
 
             V2 sandboxes created with this method are not currently returned by
-            `Sandbox.list()` and cannot be looked up with `Sandbox.from_name()`.
-            Store `sandbox.object_id` if you need to retrieve the sandbox later, and
-            use `Sandbox.from_id(sandbox.object_id)` to reattach.
+            `Sandbox.list()`. A named sandbox can be looked up with
+            `Sandbox._experimental_from_name(app_name, name)`; otherwise store
+            `sandbox.object_id` and use `Sandbox.from_id(sandbox.object_id)` to
+            reattach.
             """
             ...
 
@@ -1789,9 +1820,10 @@ class Sandbox(modal.object.Object):
             (e.g. `region="us-east-1"`).
 
             V2 sandboxes created with this method are not currently returned by
-            `Sandbox.list()` and cannot be looked up with `Sandbox.from_name()`.
-            Store `sandbox.object_id` if you need to retrieve the sandbox later, and
-            use `Sandbox.from_id(sandbox.object_id)` to reattach.
+            `Sandbox.list()`. A named sandbox can be looked up with
+            `Sandbox._experimental_from_name(app_name, name)`; otherwise store
+            `sandbox.object_id` and use `Sandbox.from_id(sandbox.object_id)` to
+            reattach.
             """
             ...
 
@@ -1892,6 +1924,63 @@ class Sandbox(modal.object.Object):
 
     from_name: typing.ClassVar[__from_name_spec]
 
+    class ___experimental_from_name_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            app_name: str,
+            name: str,
+            *,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> Sandbox:
+            """Get a running V2 Sandbox by name from a deployed App.
+
+            This looks up V2 sandboxes, ie sandboxes created via `modal.Sandbox._experimental_create`.
+
+            Args:
+                app_name: Name of the deployed app to look up the sandbox under.
+                name: Sandbox name to resolve.
+                environment_name: Optional environment name for the lookup; defaults to the configured environment.
+                client: Modal client to use for the RPC; defaults to `Client.from_env()` when omitted.
+
+            Returns:
+                A `Sandbox` handle for the running sandbox.
+
+            Raises:
+                NotFoundError: If no running sandbox exists with the given name.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            app_name: str,
+            name: str,
+            *,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> Sandbox:
+            """Get a running V2 Sandbox by name from a deployed App.
+
+            This looks up V2 sandboxes, ie sandboxes created via `modal.Sandbox._experimental_create`.
+
+            Args:
+                app_name: Name of the deployed app to look up the sandbox under.
+                name: Sandbox name to resolve.
+                environment_name: Optional environment name for the lookup; defaults to the configured environment.
+                client: Modal client to use for the RPC; defaults to `Client.from_env()` when omitted.
+
+            Returns:
+                A `Sandbox` handle for the running sandbox.
+
+            Raises:
+                NotFoundError: If no running sandbox exists with the given name.
+            """
+            ...
+
+    _experimental_from_name: typing.ClassVar[___experimental_from_name_spec]
+
     class __from_id_spec(typing_extensions.Protocol):
         def __call__(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox:
             """Construct a Sandbox from an id and look up the Sandbox result.
@@ -2864,15 +2953,20 @@ class Sandbox(modal.object.Object):
 
     class ___experimental_list_spec(typing_extensions.Protocol):
         def __call__(
-            self, /, *, app_id: typing.Optional[str] = None, client: typing.Optional[modal.client.Client] = None
+            self,
+            /,
+            *,
+            app_id: typing.Optional[str] = None,
+            tags: typing.Optional[dict[str, str]] = None,
+            client: typing.Optional[modal.client.Client] = None,
         ) -> typing.Generator[Sandbox, None, None]:
             """List v2 Sandboxes in an App.
 
             This function lists v2 sandboxes, ie sandboxes created via modal.Sandbox._experimental_create.
-            Filtering based on tags is not yet supported.
 
             Args:
                 app_id: The App to list Sandboxes under.
+                tags: If set, only sandboxes containing at least these tags are returned.
                 client: Optional client to use for the session.
 
             Yields:
@@ -2881,15 +2975,20 @@ class Sandbox(modal.object.Object):
             ...
 
         def aio(
-            self, /, *, app_id: typing.Optional[str] = None, client: typing.Optional[modal.client.Client] = None
+            self,
+            /,
+            *,
+            app_id: typing.Optional[str] = None,
+            tags: typing.Optional[dict[str, str]] = None,
+            client: typing.Optional[modal.client.Client] = None,
         ) -> collections.abc.AsyncGenerator[Sandbox, None]:
             """List v2 Sandboxes in an App.
 
             This function lists v2 sandboxes, ie sandboxes created via modal.Sandbox._experimental_create.
-            Filtering based on tags is not yet supported.
 
             Args:
                 app_id: The App to list Sandboxes under.
+                tags: If set, only sandboxes containing at least these tags are returned.
                 client: Optional client to use for the session.
 
             Yields:

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/types.py

@@ -5,7 +5,7 @@ import enum
 from dataclasses import FrozenInstanceError, dataclass
 from datetime import datetime, timezone
 from decimal import Decimal
-from typing import Any, Iterable, Optional
+from typing import Any, Iterable, Optional, TypedDict
 
 from modal_proto import api_pb2
 
@@ -90,6 +90,12 @@ class SecretInfo:
     created_by: str | None
 
 
+class VolumeCreateOptions(TypedDict, total=False):
+    """Options used when creating a Volume."""
+
+    experimental_options: dict[str, Any]
+
+
 @dataclass
 class VolumeInfo:
     """Information about a Volume object."""

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/volume.py

@@ -71,7 +71,7 @@ from ._utils.name_utils import check_object_name
 from ._utils.time_utils import as_timestamp, timestamp_to_localized_dt
 from .client import _Client
 from .config import logger
-from .types import FileEntry, FileEntryType as FileEntryType, VolumeInfo
+from .types import FileEntry, FileEntryType as FileEntryType, VolumeCreateOptions, VolumeInfo
 
 # Max duration for uploading to volumes files
 # As a guide, files >40GiB will take >10 minutes to upload.
@@ -120,6 +120,20 @@ def _validate_volume_version(
         )
 
 
+def _experimental_options_to_string_map(experimental_options: dict[str, Any]) -> dict[str, str]:
+    """Coerce experimental option values to strings for the proto's string map."""
+    return {str(key): str(value) for key, value in experimental_options.items()}
+
+
+def _volume_create_options_to_proto(create_options: "VolumeCreateOptions | None") -> api_pb2.VolumeCreateOptions:
+    """Build a VolumeCreateOptions proto message from the public TypedDict."""
+    if not create_options:
+        return api_pb2.VolumeCreateOptions()
+    return api_pb2.VolumeCreateOptions(
+        experimental_options=_experimental_options_to_string_map(create_options.get("experimental_options", {})),
+    )
+
+
 class _VolumeManager:
     """Namespace with methods for managing named Volume objects."""
 
@@ -131,6 +145,7 @@ class _VolumeManager:
         allow_existing: bool = False,
         environment_name: str | None = None,
         client: _Client | None = None,
+        experimental_options: dict[str, Any] | None = None,
     ) -> None:
         """Create a new named Volume in the workspace environment.
 
@@ -144,6 +159,7 @@ class _VolumeManager:
             allow_existing: If True, do nothing when a Volume with this name already exists.
             environment_name: Environment to create in; defaults to the active environment.
             client: Modal client to use; defaults to `Client.from_env()` when omitted.
+            experimental_options: Experimental options to create Volume with.
 
         Examples:
             ```python notest
@@ -181,6 +197,9 @@ class _VolumeManager:
             environment_name=_get_environment_name(environment_name),
             object_creation_type=object_creation_type,
             version=version,
+            create_options=_volume_create_options_to_proto(
+                VolumeCreateOptions(experimental_options=experimental_options or {})
+            ),
         )
         try:
             response = await client.stub.VolumeGetOrCreate(req)
@@ -545,6 +564,7 @@ class _Volume(_Object, type_prefix="vo"):
         environment_name: str | None = None,
         create_if_missing: bool = False,
         version: "modal_proto.api_pb2.VolumeFsVersion.ValueType | None" = None,
+        create_options: "VolumeCreateOptions | None" = None,
         client: _Client | None = None,
     ) -> "_Volume":
         """Reference a Volume by name, optionally creating it on the server first.
@@ -556,6 +576,7 @@ class _Volume(_Object, type_prefix="vo"):
             environment_name: Environment to resolve the name in; defaults to the active environment.
             create_if_missing: If True, create the Volume when it does not already exist.
             version: Optional VolumeFS backend version; must match an existing Volume when set.
+            create_options: Applied when creating the Volume. If an existing Volume, validates options are consistent.
             client: Modal client to use for loading; defaults to `Client.from_env()` when omitted.
 
         Returns:
@@ -580,6 +601,7 @@ class _Volume(_Object, type_prefix="vo"):
                 environment_name=load_context.environment_name,
                 object_creation_type=(api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING if create_if_missing else None),
                 version=version,
+                create_options=_volume_create_options_to_proto(create_options),
             )
             response = await load_context.client.stub.VolumeGetOrCreate(req)
             if version is not None:
@@ -650,6 +672,7 @@ class _Volume(_Object, type_prefix="vo"):
         client: _Client | None = None,
         environment_name: str | None = None,
         version: "modal_proto.api_pb2.VolumeFsVersion.ValueType | None" = None,
+        create_options: "VolumeCreateOptions | None" = None,
         _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,  # mdmd:line-hidden
     ) -> AsyncGenerator["_Volume", None]:
         """Create an anonymous Volume that exists for the duration of the context manager.
@@ -658,6 +681,7 @@ class _Volume(_Object, type_prefix="vo"):
             client: Modal client to use; defaults to `Client.from_env()` when omitted.
             environment_name: Environment for the ephemeral Volume; defaults to the active environment.
             version: Optional VolumeFS backend version for the ephemeral Volume.
+            create_options: Options applied when creating the ephemeral Volume.
 
         Examples:
             ```python
@@ -678,6 +702,7 @@ class _Volume(_Object, type_prefix="vo"):
             object_creation_type=api_pb2.OBJECT_CREATION_TYPE_EPHEMERAL,
             environment_name=_get_environment_name(environment_name),
             version=version,
+            create_options=_volume_create_options_to_proto(create_options),
         )
         response = await client.stub.VolumeGetOrCreate(request)
         async with TaskContext() as tc:

{modal-1.5.2.dev20 → modal-1.5.2.dev21}/modal/volume.pyi

@@ -28,6 +28,16 @@ def _validate_volume_version(requested_version: int, actual_version: int, volume
     """Validate that the returned volume version matches the requested version."""
     ...
 
+def _experimental_options_to_string_map(experimental_options: dict[str, typing.Any]) -> dict[str, str]:
+    """Coerce experimental option values to strings for the proto's string map."""
+    ...
+
+def _volume_create_options_to_proto(
+    create_options: typing.Optional[modal.types.VolumeCreateOptions],
+) -> modal_proto.api_pb2.VolumeCreateOptions:
+    """Build a VolumeCreateOptions proto message from the public TypedDict."""
+    ...
+
 class _VolumeManager:
     """Namespace with methods for managing named Volume objects."""
     async def create(
@@ -38,6 +48,7 @@ class _VolumeManager:
         allow_existing: bool = False,
         environment_name: typing.Optional[str] = None,
         client: typing.Optional[modal.client._Client] = None,
+        experimental_options: typing.Optional[dict[str, typing.Any]] = None,
     ) -> None:
         """Create a new named Volume in the workspace environment.
 
@@ -51,6 +62,7 @@ class _VolumeManager:
             allow_existing: If True, do nothing when a Volume with this name already exists.
             environment_name: Environment to create in; defaults to the active environment.
             client: Modal client to use; defaults to `Client.from_env()` when omitted.
+            experimental_options: Experimental options to create Volume with.
 
         Examples:
             ```python notest
@@ -167,6 +179,7 @@ class VolumeManager:
             allow_existing: bool = False,
             environment_name: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
+            experimental_options: typing.Optional[dict[str, typing.Any]] = None,
         ) -> None:
             """Create a new named Volume in the workspace environment.
 
@@ -180,6 +193,7 @@ class VolumeManager:
                 allow_existing: If True, do nothing when a Volume with this name already exists.
                 environment_name: Environment to create in; defaults to the active environment.
                 client: Modal client to use; defaults to `Client.from_env()` when omitted.
+                experimental_options: Experimental options to create Volume with.
 
             Examples:
                 ```python notest
@@ -212,6 +226,7 @@ class VolumeManager:
             allow_existing: bool = False,
             environment_name: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
+            experimental_options: typing.Optional[dict[str, typing.Any]] = None,
         ) -> None:
             """Create a new named Volume in the workspace environment.
 
@@ -225,6 +240,7 @@ class VolumeManager:
                 allow_existing: If True, do nothing when a Volume with this name already exists.
                 environment_name: Environment to create in; defaults to the active environment.
                 client: Modal client to use; defaults to `Client.from_env()` when omitted.
+                experimental_options: Experimental options to create Volume with.
 
             Examples:
                 ```python notest
@@ -564,6 +580,7 @@ class _Volume(modal._object._Object):
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
         version: typing.Optional[int] = None,
+        create_options: typing.Optional[modal.types.VolumeCreateOptions] = None,
         client: typing.Optional[modal.client._Client] = None,
     ) -> _Volume:
         """Reference a Volume by name, optionally creating it on the server first.
@@ -575,6 +592,7 @@ class _Volume(modal._object._Object):
             environment_name: Environment to resolve the name in; defaults to the active environment.
             create_if_missing: If True, create the Volume when it does not already exist.
             version: Optional VolumeFS backend version; must match an existing Volume when set.
+            create_options: Applied when creating the Volume. If an existing Volume, validates options are consistent.
             client: Modal client to use for loading; defaults to `Client.from_env()` when omitted.
 
         Returns:
@@ -630,6 +648,7 @@ class _Volume(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         version: typing.Optional[int] = None,
+        create_options: typing.Optional[modal.types.VolumeCreateOptions] = None,
         _heartbeat_sleep: float = 300,
     ) -> typing.AsyncContextManager[_Volume]:
         """Create an anonymous Volume that exists for the duration of the context manager.
@@ -638,6 +657,7 @@ class _Volume(modal._object._Object):
             client: Modal client to use; defaults to `Client.from_env()` when omitted.
             environment_name: Environment for the ephemeral Volume; defaults to the active environment.
             version: Optional VolumeFS backend version for the ephemeral Volume.
+            create_options: Options applied when creating the ephemeral Volume.
 
         Examples:
             ```python
@@ -928,6 +948,7 @@ class Volume(modal.object.Object):
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
         version: typing.Optional[int] = None,
+        create_options: typing.Optional[modal.types.VolumeCreateOptions] = None,
         client: typing.Optional[modal.client.Client] = None,
     ) -> Volume:
         """Reference a Volume by name, optionally creating it on the server first.
@@ -939,6 +960,7 @@ class Volume(modal.object.Object):
             environment_name: Environment to resolve the name in; defaults to the active environment.
             create_if_missing: If True, create the Volume when it does not already exist.
             version: Optional VolumeFS backend version; must match an existing Volume when set.
+            create_options: Applied when creating the Volume. If an existing Volume, validates options are consistent.
             client: Modal client to use for loading; defaults to `Client.from_env()` when omitted.
 
         Returns:
@@ -995,6 +1017,7 @@ class Volume(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             version: typing.Optional[int] = None,
+            create_options: typing.Optional[modal.types.VolumeCreateOptions] = None,
             _heartbeat_sleep: float = 300,
         ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Volume]:
             """Create an anonymous Volume that exists for the duration of the context manager.
@@ -1003,6 +1026,7 @@ class Volume(modal.object.Object):
                 client: Modal client to use; defaults to `Client.from_env()` when omitted.
                 environment_name: Environment for the ephemeral Volume; defaults to the active environment.
                 version: Optional VolumeFS backend version for the ephemeral Volume.
+                create_options: Options applied when creating the ephemeral Volume.
 
             Examples:
                 ```python
@@ -1025,6 +1049,7 @@ class Volume(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             version: typing.Optional[int] = None,
+            create_options: typing.Optional[modal.types.VolumeCreateOptions] = None,
             _heartbeat_sleep: float = 300,
         ) -> typing.AsyncContextManager[Volume]:
             """Create an anonymous Volume that exists for the duration of the context manager.
@@ -1033,6 +1058,7 @@ class Volume(modal.object.Object):
                 client: Modal client to use; defaults to `Client.from_env()` when omitted.
                 environment_name: Environment for the ephemeral Volume; defaults to the active environment.
                 version: Optional VolumeFS backend version for the ephemeral Volume.
+                create_options: Options applied when creating the ephemeral Volume.
 
             Examples:
                 ```python