modal 1.6.1.dev1__tar.gz → 1.6.1.dev3__tar.gz

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.6.1.dev1
+Version: 1.6.1.dev3
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0
@@ -21,9 +21,9 @@ Requires-Dist: certifi
 Requires-Dist: click~=8.1
 Requires-Dist: grpclib<0.4.10,>=0.4.7; python_version < "3.14"
 Requires-Dist: grpclib<0.4.10,>=0.4.9; python_version >= "3.14"
-Requires-Dist: protobuf!=4.24.0,<7.0,>=3.19
+Requires-Dist: protobuf!=4.24.0,<8.0,>=3.19
 Requires-Dist: rich>=12.0.0
-Requires-Dist: synchronicity~=0.12.5
+Requires-Dist: synchronicity~=0.12.6
 Requires-Dist: toml
 Requires-Dist: types-certifi
 Requires-Dist: types-toml

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/_environments.py

@@ -22,7 +22,7 @@ from ._utils.time_utils import is_utc_month_aligned, parse_billing_cycle
 from .client import _Client
 from .config import config, logger
 from .exception import InvalidError, WorkspaceManagementError
-from .types import BillingReportItem, EnvironmentBillingSummary
+from .types import AppInfo, BillingReportItem, EnvironmentBillingSummary
 
 if TYPE_CHECKING:
     import modal
@@ -346,6 +346,7 @@ class _EnvironmentAppsManager:
                 self._environment.name,
                 self._environment.client,
                 description=item.description or None,
+                info=AppInfo._from_proto(item.metadata, item.app_id),
             )
             for item in response.apps
             if item.state not in stopped_app_states

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/_output/status.py

@@ -13,9 +13,7 @@ from .manager import OutputManager
 
 
 def _get_annotation_for_web_url(url_info: api_pb2.WebUrlInfo) -> str:
-    if url_info.truncated:
-        suffix = " [grey70](label truncated)[/grey70]"
-    elif url_info.label_stolen:
+    if url_info.label_stolen:
         suffix = " [grey70](label stolen)[/grey70]"
     else:
         suffix = ""

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/_server.py

@@ -1,7 +1,10 @@
 # Copyright Modal Labs 2025
+import asyncio
 import inspect
 import json
+import time
 import typing
+import uuid
 from datetime import datetime, timedelta, timezone
 
 from typing_extensions import Self
@@ -477,9 +480,8 @@ class _Server:
         return ServerStats._from_proto(stats)
 
 
-@retry(n_attempts=5, base_delay=0.5, attempt_timeout=65, total_timeout=200)
 async def _post_session_control(url: str, headers: dict[str, str]) -> tuple[int, str, str]:
-    """POST to a sticky session control endpoint, retrying connection errors and 5xx. Returns (status, reason, body)."""
+    """POST to a sticky session control endpoint, raising on 5xx."""
     async with ClientSessionRegistry.get_session().post(url, headers=headers) as resp:
         body = await resp.text()
         if resp.status >= 400:
@@ -489,6 +491,28 @@ async def _post_session_control(url: str, headers: dict[str, str]) -> tuple[int,
         return resp.status, resp.reason or "", body
 
 
+async def _post_session_start(base_url: str, fn: _Function, idle_timeout: int) -> tuple[int, str, str]:
+    idempotency_key = str(uuid.uuid4())
+    start_timestamp = str(time.time())
+
+    @retry(n_attempts=5, base_delay=0.5, attempt_timeout=None, total_timeout=1515)
+    async def attempt() -> tuple[int, str, str]:
+        headers = {
+            "Modal-Authorization": f"Bearer {await fn._get_flash_auth_token()}",
+            "x-idempotency-key": idempotency_key,
+            "x-modal-timestamp": start_timestamp,
+            "x-modal-server-session-idle-timeout": str(idle_timeout),
+        }
+        return await _post_session_control(f"{base_url}/_modal/sessions/start", headers)
+
+    return await attempt()
+
+
+@retry(n_attempts=3, base_delay=0.5, attempt_timeout=None, total_timeout=60)
+async def _post_session_terminate(base_url: str, headers: dict[str, str]) -> tuple[int, str, str]:
+    return await _post_session_control(f"{base_url}/_modal/sessions/terminate", headers)
+
+
 class _ServerSessionsManager:
     """mdmd:namespace"""
 
@@ -507,6 +531,10 @@ class _ServerSessionsManager:
         session has had no connections for `idle_timeout` seconds or is terminated. A container won't be scaled down
         for as long as it holds a live session.
 
+        If no container has room for the session, the call waits for additional capacity. It will block for
+        up to 25 minutes before giving up. To control the wait per call, use the HTTP API and apply your own retry
+        policy.
+
         Args:
             idle_timeout: Seconds without an in-flight request before the session ends.
 
@@ -531,13 +559,10 @@ class _ServerSessionsManager:
         self._validate()
         assert url is not None, "Server has no URL."
 
-        headers = {
-            "Modal-Authorization": f"Bearer {await fn._get_flash_auth_token()}",
-            "x-modal-server-session-idle-timeout": str(idle_timeout),
-        }
-
         try:
-            status, reason, body = await _post_session_control(f"{url}/_modal/sessions/start", headers)
+            status, reason, body = await _post_session_start(url, fn, idle_timeout)
+        except asyncio.TimeoutError:
+            raise asyncio.TimeoutError("Failed to start session: timed out") from None
         except ServiceError as exc:
             raise ExecutionError(f"Failed to start session: {exc}") from None
         if status >= 400:
@@ -576,7 +601,7 @@ class _ServerSessionsManager:
             "x-modal-server-session-token": token,
         }
         try:
-            status, reason, _body = await _post_session_control(f"{url}/_modal/sessions/terminate", headers)
+            status, reason, _body = await _post_session_terminate(url, headers)
         except ServiceError as exc:
             raise ExecutionError(f"Failed to terminate session: {exc}") from None
         if status == 404:

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/_server.pyi

@@ -272,9 +272,14 @@ class _Server:
         ...
 
 async def _post_session_control(url: str, headers: dict[str, str]) -> tuple[int, str, str]:
-    """POST to a sticky session control endpoint, retrying connection errors and 5xx. Returns (status, reason, body)."""
+    """POST to a sticky session control endpoint, raising on 5xx."""
     ...
 
+async def _post_session_start(
+    base_url: str, fn: modal._functions._Function, idle_timeout: int
+) -> tuple[int, str, str]: ...
+async def _post_session_terminate(base_url: str, headers: dict[str, str]) -> tuple[int, str, str]: ...
+
 class _ServerSessionsManager:
     """mdmd:namespace"""
     def __init__(self, server: _Server):
@@ -289,6 +294,10 @@ class _ServerSessionsManager:
         session has had no connections for `idle_timeout` seconds or is terminated. A container won't be scaled down
         for as long as it holds a live session.
 
+        If no container has room for the session, the call waits for additional capacity. It will block for
+        up to 25 minutes before giving up. To control the wait per call, use the HTTP API and apply your own retry
+        policy.
+
         Args:
             idle_timeout: Seconds without an in-flight request before the session ends.
 
@@ -342,6 +351,10 @@ class ServerSessionsManager:
             session has had no connections for `idle_timeout` seconds or is terminated. A container won't be scaled down
             for as long as it holds a live session.
 
+            If no container has room for the session, the call waits for additional capacity. It will block for
+            up to 25 minutes before giving up. To control the wait per call, use the HTTP API and apply your own retry
+            policy.
+
             Args:
                 idle_timeout: Seconds without an in-flight request before the session ends.
 
@@ -367,6 +380,10 @@ class ServerSessionsManager:
             session has had no connections for `idle_timeout` seconds or is terminated. A container won't be scaled down
             for as long as it holds a live session.
 
+            If no container has room for the session, the call waits for additional capacity. It will block for
+            up to 25 minutes before giving up. To control the wait per call, use the HTTP API and apply your own retry
+            policy.
+
             Args:
                 idle_timeout: Seconds without an in-flight request before the session ends.
 

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/cli/function.py

@@ -112,6 +112,7 @@ def _time_range_stats_json(response: api_pb2.FunctionGetTimeRangeStatsResponse)
         "input_percentile_stats": _distribution_map_json(
             cast(dict[str, api_pb2.StatsPercentileDistribution], response.input_percentile_stats)
         ),
+        "container_total_count": response.container_total_count,
         "container_started_count": response.container_started_count,
         "container_error_count": response.container_error_count,
         "container_creating_at_end_count": response.container_creating_at_end_count,
@@ -794,9 +795,10 @@ async def stats(
 
     output.print("")
     container_count = resp.container_started_count + resp.container_error_count
+    total_containers = resp.container_total_count
     container_heading = Text("Containers", style=stats_style(STATS_SECTION_STYLE, use_color))
     container_heading.append(" " * (46 - len("Containers")))
-    container_heading.append(f"{container_count:,} total (")
+    container_heading.append(f"{total_containers:,} Total (")
     container_heading.append(
         f"{resp.container_creating_at_end_count:,} creating",
         style=progress_style(resp.container_creating_at_end_count, use_color),
@@ -806,12 +808,12 @@ async def stats(
 
     container_counts = Text("  ")
     container_counts.append(
-        _count_with_percentage(resp.container_started_count, container_count, "started"),
+        f"{resp.container_started_count:,} started",
         style=success_style(resp.container_started_count, container_count, use_color),
     )
     container_counts.append(" · ")
     container_counts.append(
-        _count_with_percentage(resp.container_error_count, container_count, "errored"),
+        f"{resp.container_error_count:,} errored",
         style=problem_style(resp.container_error_count, container_count, use_color),
     )
     output.print(container_counts)

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/cli/server.py

@@ -33,7 +33,6 @@ from ._stats import (
     STATS_METADATA_STYLE,
     STATS_PROBLEM_STYLE,
     STATS_SECTION_STYLE,
-    _count_with_percentage,
     _distribution_map_json,
     _metric_rows,
     _percentile_table,
@@ -560,6 +559,7 @@ def _stats_json(
         "request_rate_per_second": history.request_rate_per_second,
         "container_started_count": history.container_started_count,
         "container_error_count": history.container_error_count,
+        "container_total_count": history.container_total_count,
         "container_creating_at_end_count": history.container_creating_at_end_count,
         "request_percentile_stats": _distribution_map_json(
             cast(dict[str, api_pb2.StatsPercentileDistribution], history.request_percentile_stats)
@@ -754,9 +754,10 @@ async def _run_server_stats(
 
     output.print("")
     container_count = history.container_started_count + history.container_error_count
+    container_total_count = history.container_total_count
     container_heading = Text("Containers", style=stats_style(STATS_SECTION_STYLE, use_color))
     container_heading.append(" " * (46 - len("Containers")))
-    container_heading.append(f"{container_count:,} total (")
+    container_heading.append(f"{container_total_count:,} Total (")
     container_heading.append(
         f"{history.container_creating_at_end_count:,} creating",
         style=progress_style(history.container_creating_at_end_count, use_color),
@@ -766,12 +767,12 @@ async def _run_server_stats(
 
     container_counts = Text("  ")
     container_counts.append(
-        _count_with_percentage(history.container_started_count, container_count, "started"),
+        f"{history.container_started_count:,} started",
         style=success_style(history.container_started_count, container_count, use_color),
     )
     container_counts.append(" · ")
     container_counts.append(
-        _count_with_percentage(history.container_error_count, container_count, "errored"),
+        f"{history.container_error_count:,} errored",
         style=problem_style(history.container_error_count, container_count, use_color),
     )
     output.print(container_counts)

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/client.pyi

@@ -80,7 +80,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.1.dev1",
+        version: str = "1.6.1.dev3",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):
@@ -290,7 +290,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.1.dev1",
+        version: str = "1.6.1.dev3",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/config.py

@@ -134,13 +134,9 @@ def _agent_environment() -> str | None:
 
     Returns the agent name if detected, or None otherwise.
 
-    Checks the emerging `AGENT` standard variable first, then falls back to
-    tool-specific environment variables used by known agent harnesses.
+    Checks tool-specific environment variables used by known agent harnesses
+    first, then falls back to the emerging `AGENT` and `AI_AGENT` standards.
     """
-    # Emerging standard: AGENT=<name>
-    if agent := os.environ.get("AGENT"):
-        return agent
-
     # Tool-specific environment variables
     _TOOL_SPECIFIC_ENV_VARS: list[tuple[str, str]] = [
         ("CLAUDECODE", "claude-code"),
@@ -152,11 +148,23 @@ def _agent_environment() -> str | None:
         ("OPENCODE_CLIENT", "opencode"),
         ("GOOSE_TERMINAL", "goose"),  # honk
         ("TRAE_AI_SHELL_ID", "trae"),
+        ("PI_CODING_AGENT", "pi"),
+        ("COPILOT_AGENT_SESSION_ID", "copilot"),
+        ("ANTIGRAVITY_AGENT", "antigravity"),
+        ("JUNIE_SHIM_PATH", "junie"),
     ]
     for env_var, agent_name in _TOOL_SPECIFIC_ENV_VARS:
         if os.environ.get(env_var):
             return agent_name
 
+    # Emerging standards, checked last because neither value is normalized.
+    # `AGENT` may be a bare `1` rather than a name (opencode), and `AI_AGENT`
+    # may embed a version or suffix (e.g. `claude-code_2-1-268_agent`).
+    if agent := os.environ.get("AGENT"):
+        return agent
+    if agent := os.environ.get("AI_AGENT"):
+        return agent
+
     return None
 
 

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/object.pyi

@@ -45,8 +45,6 @@ class Object:
     def _is_hydrated(self) -> bool: ...
     @_is_hydrated.setter
     def _is_hydrated(self, value: bool): ...
-    @classmethod
-    def __init_subclass__(cls, type_prefix: typing.Optional[str] = None): ...
     def _init(
         self,
         rep: str,

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/sandbox.py

@@ -3121,6 +3121,7 @@ class _SidecarManager:
         outbound_cidr_allowlist: Sequence[str] | None = None,
         outbound_domain_allowlist: Sequence[str] | None = None,
         include_oidc_identity_token: bool = False,
+        proxy: _Proxy | None = None,
         pty: bool = False,
         experimental_memory_reserve_consume_mib: int | None = None,
     ) -> _SidecarContainer:
@@ -3153,6 +3154,8 @@ class _SidecarManager:
             include_oidc_identity_token: If True, the sidecar receives a MODAL_IDENTITY_TOKEN env var for
                 OIDC-based auth (e.g. to AWS, GCP). The token identifies the sidecar container itself,
                 not the main container. Not supported for GPU Sandboxes.
+            proxy: Reference to a Modal Proxy to use in front of this sidecar. Not supported for GPU
+                Sandboxes.
             pty: Whether to enable PTY for the sidecar container.
             experimental_memory_reserve_consume_mib: Memory, in MiB, this sidecar consumes from the Sandbox's
                 sidecar memory reserve (the experimental `vm_sidecar_memory_reserve_mib` option).
@@ -3188,6 +3191,13 @@ class _SidecarManager:
                 "CloudBucketMount is not supported in sidecars when MODAL_USE_CONTROL_PLANE_SIDECAR_CREATE=0 is set; "
                 "unset it to use cloud bucket mounts."
             )
+        if proxy is not None and not self._sandbox._is_v2:
+            raise InvalidError("Sandbox._experimental_sidecars.create(proxy=...) is not supported for GPU Sandboxes.")
+        if proxy is not None and not via_control_plane:
+            raise InvalidError(
+                "Sandbox._experimental_sidecars.create(proxy=...) is not supported when "
+                f"{_CONTROL_PLANE_SIDECAR_CREATE_ENV_VAR}=0 is set; unset it to use a proxy."
+            )
 
         if include_oidc_identity_token and not self._sandbox._is_v2:
             raise InvalidError("include_oidc_identity_token is not supported for GPU Sandboxes.")
@@ -3224,12 +3234,18 @@ class _SidecarManager:
             for _, mount in cloud_bucket_mounts
             if mount.secret is not None and not mount.secret._is_ephemeral
         ]
-        hydrate_coros = (
-            [secret.hydrate(client=self._sandbox._client) for secret in resolvable_secrets]
-            + [volume.hydrate(client=self._sandbox._client) for _, volume in validated_volumes]
-            + [secret.hydrate(client=self._sandbox._client) for secret in bucket_credential_secrets]
-        )
-        await TaskContext.gather(*hydrate_coros)
+        resolver = Resolver()
+        async with TaskContext() as tc:
+            load_context = LoadContext(client=self._sandbox._client, task_context=tc)
+            dependencies = [
+                *resolvable_secrets,
+                *(volume for _, volume in validated_volumes),
+                *bucket_credential_secrets,
+                *([proxy] if proxy is not None else []),
+            ]
+            await asyncio.gather(
+                *(resolver.load(dependency, load_context) for dependency in dependencies if not dependency._is_hydrated)
+            )
 
         # `env` takes precedence over environment variables from secrets
         env_dict = _local_secret_env(secrets) | (env or {})
@@ -3257,6 +3273,7 @@ class _SidecarManager:
                 cloud_bucket_mounts=cloud_bucket_mount_protos,
                 network_access=network_access,
                 include_oidc_identity_token=include_oidc_identity_token,
+                proxy_id=(proxy.object_id if proxy else None),
                 pty_info=pty_info,
                 resources=(
                     api_pb2.Resources(memory_mb=experimental_memory_reserve_consume_mib)

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/sandbox.pyi

@@ -1298,6 +1298,7 @@ class _SidecarManager:
         outbound_cidr_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
         outbound_domain_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
         include_oidc_identity_token: bool = False,
+        proxy: typing.Optional[modal.proxy._Proxy] = None,
         pty: bool = False,
         experimental_memory_reserve_consume_mib: typing.Optional[int] = None,
     ) -> _SidecarContainer:
@@ -1330,6 +1331,8 @@ class _SidecarManager:
             include_oidc_identity_token: If True, the sidecar receives a MODAL_IDENTITY_TOKEN env var for
                 OIDC-based auth (e.g. to AWS, GCP). The token identifies the sidecar container itself,
                 not the main container. Not supported for GPU Sandboxes.
+            proxy: Reference to a Modal Proxy to use in front of this sidecar. Not supported for GPU
+                Sandboxes.
             pty: Whether to enable PTY for the sidecar container.
             experimental_memory_reserve_consume_mib: Memory, in MiB, this sidecar consumes from the Sandbox's
                 sidecar memory reserve (the experimental `vm_sidecar_memory_reserve_mib` option).
@@ -1782,6 +1785,7 @@ class SidecarManager:
             outbound_cidr_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
             outbound_domain_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
             include_oidc_identity_token: bool = False,
+            proxy: typing.Optional[modal.proxy.Proxy] = None,
             pty: bool = False,
             experimental_memory_reserve_consume_mib: typing.Optional[int] = None,
         ) -> SidecarContainer:
@@ -1814,6 +1818,8 @@ class SidecarManager:
                 include_oidc_identity_token: If True, the sidecar receives a MODAL_IDENTITY_TOKEN env var for
                     OIDC-based auth (e.g. to AWS, GCP). The token identifies the sidecar container itself,
                     not the main container. Not supported for GPU Sandboxes.
+                proxy: Reference to a Modal Proxy to use in front of this sidecar. Not supported for GPU
+                    Sandboxes.
                 pty: Whether to enable PTY for the sidecar container.
                 experimental_memory_reserve_consume_mib: Memory, in MiB, this sidecar consumes from the Sandbox's
                     sidecar memory reserve (the experimental `vm_sidecar_memory_reserve_mib` option).
@@ -1843,6 +1849,7 @@ class SidecarManager:
             outbound_cidr_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
             outbound_domain_allowlist: typing.Optional[collections.abc.Sequence[str]] = None,
             include_oidc_identity_token: bool = False,
+            proxy: typing.Optional[modal.proxy.Proxy] = None,
             pty: bool = False,
             experimental_memory_reserve_consume_mib: typing.Optional[int] = None,
         ) -> SidecarContainer:
@@ -1875,6 +1882,8 @@ class SidecarManager:
                 include_oidc_identity_token: If True, the sidecar receives a MODAL_IDENTITY_TOKEN env var for
                     OIDC-based auth (e.g. to AWS, GCP). The token identifies the sidecar container itself,
                     not the main container. Not supported for GPU Sandboxes.
+                proxy: Reference to a Modal Proxy to use in front of this sidecar. Not supported for GPU
+                    Sandboxes.
                 pty: Whether to enable PTY for the sidecar container.
                 experimental_memory_reserve_consume_mib: Memory, in MiB, this sidecar consumes from the Sandbox's
                     sidecar memory reserve (the experimental `vm_sidecar_memory_reserve_mib` option).

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/skills/modal/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: modal
 description: >
-  This skill provides guidance for working with the Modal cloud platform. Use
-  this skill whenever the user mentions Modal or has code that imports the
-  `modal` SDK in Python, Go, or JavaScript. This skill should also trigger when
-  the user needs to run Python code with vertical or horizontal scalability
-  (e.g. batch jobs), needs access to GPUs (e.g. AI workloads including training
-  and inference) or needs to run untrusted processes in a sandbox, since Modal
-  serves these use cases well.
+  This skill provides guidance for working with the Modal cloud platform. Read
+  this skill before answering any questions about Modal, reading any Modal docs,
+  inspecting the `modal` SDK, or interacting with any code that imports the
+  `modal` SDK in Python, Go, or JavaScript, even for simple tasks you already
+  know how to do. This skill should also trigger when the user needs to run
+  Python code with vertical or horizontal scalability (e.g. batch jobs), needs
+  access to GPUs (e.g. AI workloads including training and inference) or needs
+  to run untrusted processes in a sandbox, since Modal serves these use cases
+  well.
 ---
 
 # Overview
@@ -16,21 +18,18 @@ This is a foundational skill for working with the Modal cloud platform.
 
 Modal is a platform for AI workloads. It offers highly scalable serverless compute (including GPUs) with minimal configuration.
 
+Using the CLI or running code that depends on the `modal` library requires internet access and an authorization token. There is no "local development mode" with Modal.
+
 # Documentation
 
 The official docs are the best source for up-to-date information on the platform. Make use of them when planning, debugging, or answering questions!
 
-Modal's documentation is outlined at https://modal.com/llms.txt. This file contains titles and URLs for all public docs; reading it directly will guide you to specific content.
-
-The docs are divided into three sections:
+Modal's latest documentation, which may cover features introduced in newer SDK versions, is outlined at https://modal.com/llms.txt. This file contains titles and URLs for all public docs; reading it directly will guide you to specific content. Fetch the docs using a `.md` extension to get plain text.
 
-- _Guide_ pages have explanations of Modal features, primitives, and workflows
-- _API Reference_ pages have detailed information about each component of the SDK
-- _Examples_ pages contain didactic examples of various AI applications on Modal
+When installed via the Modal CLI, this skill installs local documentation in `references/` unless `--no-docs` is passed:
 
-Fetch the docs using a `.md` extension to get plain text.
-
-If this skill has been installed via the `modal` CLI, the docs are also bundled locally under `references/`.
+- `api/`: An API reference generated locally from the signatures and docstrings of the SDK used to install or update the skill.
+- `guide/` and `examples/`: Guides and examples downloaded from the online docs. These reflect the website at download time and may cover features unavailable in that SDK version.
 
 You can also refer to https://modal.com/llms-full.txt, which aggregates all docs in a single very large file. Do *not* read this into your main context, but it may be useful for searching.
 
@@ -46,6 +45,8 @@ Tip: many CLI commands accept a `--json` flag to make their output more easily p
 
 The `modal` CLI is part of the Python SDK and executes in a Python runtime. Depending on the user's preferred Python development workflow, you may need to prefix `modal` CLI invocations with, e.g., `uv run` to ensure a consistent Python environment. The CLI can also be used via `uvx` as a standalone tool, but only do this when working outside of a Python project.
 
+Do not run Modal CLI commands with an attached terminal (TTY/PTY), so logs appear as plain text rather than spinner redraws.
+
 # Getting up to date
 
 You have significant knowledge about Modal from your training data but may not be aware of new features or recent changes to the API. Modal is continuously adding new features. Reading relevant docs while planning or debugging can help you discover the most up-to-date way to accomplish a task on Modal.
@@ -56,19 +57,13 @@ The Modal CLI provides a `modal changelog` command for learning about recent cha
 - `modal changelog --since [VERSION]` when migrating a codebase to a newer version
 - `modal changelog --newer` to discover features that would be available on update
 
-Note: `modal changelog` requires network access.
+Note: the output of `modal changelog` may be long. Do not load it fully into your context.
 
 Run `modal --version` to see the SDK version that is in use.
 
 If your code exercises deprecated APIs, Modal will issue warnings. Use the warning message and related documentation to migrate your code to stable API.
 
-This skill will also be improved over time. Its version should correspond to the version of the Modal SDK that you are using. If the skill is out of date, it can be updated by running `modal skills update`.
-
-# Auth
-
-Modal is a cloud platform. Using the CLI or running code that depends on the `modal` library requires internet access and an authorization token. There is no "local development mode" with Modal.
-
-You can use the `modal token` CLI to create a new token (note: this workflow requires human user involvement) or to debug authorization issues. Token setup only needs to happen once, so assume it is configured unless you encounter issues.
+Before using this skill, check that its version in the metadata is identical to `modal --version`. If not, run `modal skills update` to update it, passing `--claude` if this skill lives under a `.claude/` directory and `--global` if it lives under the home directory rather than the project.
 
 # Async Python
 

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/types.py

@@ -181,6 +181,7 @@ class FunctionStats:
     container_error_count: int
     container_creating_at_end_count: int
     container_percentile_stats: dict[str, StatsPercentileDistribution]
+    container_total_count: int
     variant_count: int
     all_variants: bool
 
@@ -198,6 +199,7 @@ class FunctionStats:
             },
             container_started_count=proto.container_started_count,
             container_error_count=proto.container_error_count,
+            container_total_count=proto.container_total_count,
             container_creating_at_end_count=proto.container_creating_at_end_count,
             container_percentile_stats={
                 k: StatsPercentileDistribution._from_proto(v) for k, v in proto.container_percentile_stats.items()
@@ -256,6 +258,7 @@ class ServerStats:
     container_started_count: int
     container_error_count: int
     container_creating_at_end_count: int
+    container_total_count: int
     container_percentile_stats: dict[str, StatsPercentileDistribution]
     inference: InferenceStats | None
 
@@ -274,6 +277,7 @@ class ServerStats:
             container_started_count=proto.container_started_count,
             container_error_count=proto.container_error_count,
             container_creating_at_end_count=proto.container_creating_at_end_count,
+            container_total_count=proto.container_total_count,
             container_percentile_stats={
                 name: StatsPercentileDistribution._from_proto(distribution)
                 for name, distribution in proto.container_percentile_stats.items()

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/volume.py

@@ -888,6 +888,8 @@ class _Volume(_Object, type_prefix="vo"):
     async def commit(self):
         """Commit changes to a mounted volume.
 
+        Must be called inside a container that mounts the Volume.
+
         If successful, the changes made are now persisted in durable storage and available to other containers accessing
         the volume.
         """
@@ -906,6 +908,8 @@ class _Volume(_Object, type_prefix="vo"):
     async def reload(self):
         """Make latest committed state of volume available in the running container.
 
+        Must be called inside a container that mounts the Volume.
+
         Any uncommitted changes to the volume, such as new or modified files, may implicitly be committed when
         reloading.
 

{modal-1.6.1.dev1 → modal-1.6.1.dev3}/modal/volume.pyi

@@ -726,6 +726,8 @@ class _Volume(modal._object._Object):
     async def commit(self):
         """Commit changes to a mounted volume.
 
+        Must be called inside a container that mounts the Volume.
+
         If successful, the changes made are now persisted in durable storage and available to other containers accessing
         the volume.
         """
@@ -734,6 +736,8 @@ class _Volume(modal._object._Object):
     async def reload(self):
         """Make latest committed state of volume available in the running container.
 
+        Must be called inside a container that mounts the Volume.
+
         Any uncommitted changes to the volume, such as new or modified files, may implicitly be committed when
         reloading.
 
@@ -1146,6 +1150,8 @@ class Volume(modal.object.Object):
         def __call__(self, /):
             """Commit changes to a mounted volume.
 
+            Must be called inside a container that mounts the Volume.
+
             If successful, the changes made are now persisted in durable storage and available to other containers accessing
             the volume.
             """
@@ -1154,6 +1160,8 @@ class Volume(modal.object.Object):
         async def aio(self, /):
             """Commit changes to a mounted volume.
 
+            Must be called inside a container that mounts the Volume.
+
             If successful, the changes made are now persisted in durable storage and available to other containers accessing
             the volume.
             """
@@ -1165,6 +1173,8 @@ class Volume(modal.object.Object):
         def __call__(self, /):
             """Make latest committed state of volume available in the running container.
 
+            Must be called inside a container that mounts the Volume.
+
             Any uncommitted changes to the volume, such as new or modified files, may implicitly be committed when
             reloading.
 
@@ -1175,6 +1185,8 @@ class Volume(modal.object.Object):
         async def aio(self, /):
             """Make latest committed state of volume available in the running container.
 
+            Must be called inside a container that mounts the Volume.
+
             Any uncommitted changes to the volume, such as new or modified files, may implicitly be committed when
             reloading.