Modal Release Notes

We’ve added new APIs for programmatically retrieving logs on several object types: Function, Server, and FunctionCall.

Each object exposes three different methods, allowing you to stream() logs as they are generated, fetch() logs from a specific date/time range, or tail() the most recent logs.

It’s now possible to retrieve a summary of billing information across billing cycles:

• Use the modal.Workspace.billing.summary() method or the modal billing summary CLI to see workspace-level spend (broken down by category), credit usage, and the impact of any compute reservations.
• Use the modal.Environment.billing.summary() method or the modal environment billing summary CLI to see environment-level spend.

We’ve made some changes to the interfaces for managing RBAC permissions:

• We now explicitly represent all workspace member and service user roles in each Environment instead of having separate concepts for Environment membership and role.
• We’ve accordingly introduced a modal.Environment.roles interface (and modal environment roles CLI), replacing the modal.Environment.members interface and modal environment members CLI, which are now deprecated.

It’s now possible to specify one or more --compute-region options in modal endpoint create to configure the region where Endpoint containers run.

We’ve improved performance for large writes by ≈2.5x in several Sandbox filesystem methods (copy_from_local(), write_bytes(), and write_text()).

• We’ve added new interfaces for programmatic management of workspace settings:

• Use the modal.Workspace.settings.list() method or modal workspace settings list CLI to see current workspace-level settings.

• Use the modal.Workspace.settings.set() method or modal workspace settings set CLI to configure new values.

• We’ve added a modal.types module for exposing dataclasses returned from public methods as public API. The types in this module are not typically constructed by user code, but it may be useful to reference them for, e.g., adding type annotations to code that wraps the relevant Modal API.

• The modal.Function.with_options() method now accepts a routing_region argument to dynamically configure regional routing at the time of invocation.

• The modal container stop CLI now accepts a --graceful flag. With it, the container stops fetching new inputs but finishes the inputs it is currently running before exiting, instead of having them cancelled and rescheduled. Graceful stops are only supported for containers running a Modal Function or Modal Server.

• The modal container logs CLI now includes logs from the startup phase of the container.

• The modal.Workspace.members.list() method now uses "member" instead of "user" for the lowest-privilege Workspace role, matching the UI and documentation.

• The modal.Sandbox.reload_volumes() method now blocks until the Volumes have been reloaded, bounded by a new timeout argument (55 seconds by default). If the reload does not complete within timeout, modal.exception.TimeoutError is raised.

This release includes several major new features, including the debut of a new serverless compute primitive for low-latency HTTP applications (@app.server()) and a new CLI for deploying production-ready LLM inference endpoints with minimal configuration (modal endpoint).

• We’re introducing a new @app.server() decorator (and modal.Server object), representing a serverless compute primitive that shares many features with Modal Functions while being optimized for serving HTTP-based applications with ultra-low latency. Read the guide for more information.
• We’re also introducing the modal endpoint CLI, providing programmatic access to our new Endpoints product. Endpoints let you deploy production-ready LLM inference servers with minimal configuration.
• We’ve added several new SDK features for workspace configuration and observability:
  • We’ve added new billing API methods on the modal.Workspace and modal.Environment objects (workspace.billing.report() and environment.billing.report(), respectively). The new APIs include a resource-level cost breakdown (CPU, memory, and specific GPU types). We’ve also added a modal environment billing CLI for generating environment-scoped billing reports. The new workspace-level API replaces the existing modal.billing.workspace_billing_report function.
  • We’ve added support for creating and managing proxy tokens via the modal.Workspace object (workspace.proxy_tokens.create(), workspace.proxy_tokens.list(), etc.) and a new modal workspace proxy-tokens CLI. Modal Servers and Endpoints are authenticated via proxy tokens by default.
  • We’ve added a new modal workspace members CLI for querying information about workspace membership.
• The new modal curl CLI command allows you to make requests to authenticated endpoints without explicitly passing proxy token headers. This is an experimental feature and may change in the future.
• The modal app rollback command now accepts a --strategy (rolling or recreate), like modal deploy and modal app rollover.
• Sandbox connect tokens can now be scoped to a custom port (modal.Sandbox.create_connect_token(port=...)).
• It is now possible to call image.publish() on an Image constructed using modal.Image.from_id() without first calling image.build().
• The Modal Python client now respects standard environment variables for HTTP CONNECT and SOCKS4/5 proxies (HTTPS_PROXY and ALL_PROXY). Proxy support requires installing extra dependencies, i.e. using uv pip install 'modal[api-proxy-support]'. To opt out of proxy support, set MODAL_DISABLE_API_PROXY=1 or put disable_api_proxy = true in your .modal.toml profile.

This is a major release that includes several new features (named Images, version-pinned Function lookups, Sandbox domain allowlists), a new modal skills CLI, and a small number of breaking changes.

Named Images

We’re introducing a “named Image” concept, akin to a Modal-native Image registry. This feature allows you to decouple Image builds from App deployment or Sandbox creation, and it simplifies the process of sharing a canonical Image across a large number of unrelated Apps.

• The new SDK method modal.Image.publish() assigns a name to an existing Image. Names can optionally include a “tag” suffix ("{name}:{tag}") to specify variants of an Image, e.g. to apply a versioning system.
• The new SDK method modal.Image.from_name() refers directly to that Image by its name. Unlike with Image methods that specify parts of a build recipe, the modal.Image.from_name() lookup will either succeed or fail with a modal.exception.NotFoundError error, but it will never trigger a build.
• The new modal image names CLI can be used to see the current name assignments.

Version-pinned Function lookups

We’re introducing a “version-pinning” concept for Function lookups. By passing version= to modal.Function.from_name() or modal.Cls.from_name(), you can retrieve an instance that will send all inputs to the same version of the Function, even after a subsequent redeployment of its App. Additionally, any transitive invocations of other Functions in the same App will also be pinned on that version. This feature makes it easy to execute workflows that involve multiple Functions when those Functions might change in incompatible ways across deployments.

Sandbox domain allowlists

It’s now possible to restrict the domains that processes inside of a Sandbox can connect to. When you provide a list of domains to outbound_domain_allowlist=[...] in modal.Sandbox.create(), requests outside of the allowlist will be blocked by Modal infrastructure, and the denial will be recorded in the App logs.

modal skills CLI

We’ve added a new modal skills CLI for installing a foundational Modal agent skill (modal skills install) and keeping it up to date over time (modal skills update). Please help us improve it by sharing any feedback you have about its impact on agentic development with Modal.

Workspace object

We’ve added a new modal.Workspace object for programmatic interaction with your Workspace configuration. The initial release offers a workspace.members.list() method; expect more features soon.

CLI JSON output normalization

The modal CLI now normalizes the keys of its --json output by lowercasing and substituting underscores for non-alphanumeric characters.

Sandbox Filesystem watch

We’ve added a new sandbox.filesystem.watch() method to the Sandbox Filesystem API, and we’ve deprecated the alpha modal.Sandbox.watch() method. The new method has a different implementation and offers significantly improved latency and reliability.

Sandbox snapshots

We’ve made two small breaking changes around Sandbox snapshots:

• modal.Sandbox.snapshot_filesystem() and modal.Sandbox.snapshot_directory() now accept an explicit ttl= keyword argument that configures a retention interval (in seconds) for the resulting Image. Both methods default to 30 days (ttl=30 * 24 * 3600). Note: this alters the default behavior of these methods, because snapshot Images were previously persisted indefinitely. Pass an explicit ttl=None to retain the previous behavior.
• modal.Sandbox.snapshot_directory() now also accepts a timeout= keyword argument (defaulting to 55 seconds), which brings it to parity with modal.Sandbox.snapshot_filesystem(). If the snapshot does not return before the deadline, a modal.exception.TimeoutError will be raised. Note: this alters the default behavior, which previously waited indefinitely, but you can set an arbitrarily long timeout.

Removed deprecated static methods

We’ve removed several deprecated static methods (.delete() and .create_deployed()) on Modal storage objects (modal.Volume, etc.). Use the .objects.delete() and .objects.create() methods instead.

Public Beta

• This release introduces a new “regional routing” concept for Function inputs, which is now in Public Beta. By setting routing_region="..." in the @app.function() or @app.cls() decorators, you can configure the Function to route its inputs through servers in us-west, eu-west, or ap-south instead of us-east. This can reduce network latency and help you meet data residency obligations. While in Beta, this feature has a few constraints:
• A routing_region can be set only during the initial deployment of a Function and cannot be changed in a subsequent redeployment.
• Functions using regional routing can only be invoked with the .remote() and .map() methods.

• We’ve added a new modal.Environment object for programmatically managing Environments, and we’ve expanded the modal environment CLI to support RBAC configuration.

• It is now possible to dynamically configure modal.Function behavior using Function.with_options(), Function.with_concurrency(), and Function.with_batching().

• The new modal.Volume.with_mount_options() method allows you to configure a Volume mount as read-only (read_only=True) and / or limit the mount to a subdirectory of the Volume (sub_path="/some/path").

• It’s now possible to pass a custom App name for ephemeral Apps using the --name option in modal run / modal serve or by setting name= in App.run().

• We’ve added two new methods to the modal.Sandbox Filesystem API:
• sandbox.filesystem.list_files(path) lists entries (with metadata) in a given directory on the Sandbox filesystem. This replaces the alpha modal.Sandbox.ls method.
• sandbox.filesystem.stat(path) returns metadata for a specific file/symlink/directory on the Sandbox’s filesystem.

• It’s now possible to place restrictions on inbound Sandbox connections by setting inbound_cidr_allowlist=[...] in modal.Sandbox.create(). We are also adding a new outbound_cidr_allowlist=[...] parameter and deprecating the existing cidr_allowlist=[...] to avoid confusion.

• We’ve improved the reliability of the modal.Sandbox.snapshot_filesystem() operation, especially for large snapshots, and we now support setting a timeout= longer than 55s when necessary.

• Images returned by modal.Sandbox.snapshot_directory() can now be passed to modal.Sandbox.create() to use as a root filesystem for the new Sandbox.

• We’ve added a modal.Image.pipe() method to let you define reusable Image recipes that compose well with the fluent Image builder interface.

• It’s now possible to assign Sandbox tags at creation with modal.Sandbox.create(..., tags=tags).

• It’s now possible to use --chmod and --chown flags on COPY commands within modal.Image.from_dockerfile().

• We’ve improved the reliability and latency for modal shell and modal container exec CLI commands.

• We’ve added a new modal app rollover CLI command for triggering a redeployment of an App without making any code or configuration changes. A rollover replaces existing containers with fresh ones. As with modal deploy, there are two strategies for switching between deployments:

  • --strategy=rolling (the default) will smoothly migrate traffic from old containers to new containers
  • --strategy=recreate will terminate all running containers so that any subsequent inputs will go to new containers

• We’ve added a new modal bootstrap CLI command, which fetches deployable starter code for common AI applications (e.g., text generation, text-to-image, speech-to-text). This is an experiment: try it out and give us feedback!

• We’ve added two methods to the new Sandbox filesystem API:

  • sandbox.filesystem.make_directory() creates a new directory on the Sandbox filesystem
  • sandbox.filesystem.remove() deletes a file or directory from the Sandbox filesystem

• The new Sandbox filesystem methods replace the modal.Sandbox.mkdir and modal.Sandbox.rm methods, which are now deprecated.

• Sandboxes also now support sb.unmount_image(path) to remove a previously mounted Image from a path and reveal the underlying Sandbox filesystem there again.

• The modal app stop and modal container stop CLI commands now prompt for confirmation (pass --yes to skip).

• Several other modal app CLI commands will now map a name-based argument to a recently-stopped App that used that name. This is useful for, e.g., fetching logs from an App after it has been stopped.

• We’ve added a build_args parameter to modal.Image.dockerfile_commands().

• We’re introducing a concept of “readiness probes” for modal.Sandbox. This feature lets you configure a readiness check on a TCP port (modal.Probe.with_tcp()) or by executing a process (modal.Probe.with_exec()). Calling sb.wait_until_ready() will block until the Probe succeeds:

app = modal.App.lookup('sandbox-app', create_if_missing=True)
probe = modal.Probe.with_tcp(8080)
sb = modal.Sandbox.create("python3", "-m", "http.server", "8080", readiness_probe=probe, app=app)
sb.wait_until_ready()

• We fixed a longstanding bug that could cause WebSocket performance to degrade after handling hundreds of connections from the same container.
• We improved the performance of modal container logs when fetching logs for an old container.
• We fixed a bug introduced in 1.4.0 that made the modal CLI crash on typer<0.19.0.

We’ve made significant CLI enhancements so that Modal logs can be more accessible to coding agents:

• The modal app logs and modal container logs commands now have the ability to fetch historical logs using counting (e.g. --tail 1000 ) or time-based (e.g., --since 4h , --until 2026-03-15 , etc.) configuration. Note that historical log access is subject to plan-level retention limits.
• The modal container logs command also accepts --all to fetch the complete set of logs for that Container or Sandbox.
• Both CLI commands now accept a --search filter, and they can also filter by --source ( stdout / stderr / system ).
• The modal app logs command additionally accepts --function , --function-call , and --container filters.
• The modal app logs command can prefix each line with the ID of the Function, FunctionCall, or Container where it originated (e.g. --show-function-id ).
• Note that the default behavior of these commands has changed. Previously, they would follow (i.e., stream) logs by default, but you now must pass --follow to get this behavior. The new default will always show the most recent 100 log entries.

We’re releasing a new Sandbox filesystem API (currently in Beta) with significantly improved reliability and ergonomics:

• Use sb.filesystem.copy_from_local / sb.filesystem.copy_to_local to transfer file contents between your local filesystem and the Sandbox filesystem.
• Use sb.filesystem.write_text / sb.filesystem.read_text or sb.filesystem.write_bytes / sb.filesystem.read_bytes to transfer file contents between local memory and the Sandbox filesystem.
• These new APIs replace the modal.Sandbox.open method and the modal.file_io.FileIO type that it returns; the old APIs are now deprecated.

We’re introducing the concept of “deployment strategies” to give you more flexibility over what happens when redeploying your App:

• By passing modal deploy --strategy recreate (or app.deploy(strategy="recreate") in the SDK), you can immediately terminate any containers that are running when the deployment completes. This is most useful for development workflows, as it guarantees that any subsequent input will be handled by containers running the new version of the App. This trades off some downtime for certainty about when the new version will be in use.
• The disruptive “recreate” strategy is also useful when your App runs at its max_containers limit, as otherwise we are unable to bring up replacement capacity.
• The modal serve command now uses a “recreate” strategy during code updates.
• The default “rolling” strategy is unchanged. This strategy prioritizes uptime, but means that old containers may still continue handling inputs for some time.

We’ve also included a number of smaller new features and improvements:

• Sandboxes now accept an include_oidc_identity_token parameter in modal.Sandbox.create. When set to True , a MODAL_IDENTITY_TOKEN environment variable will be injected into the Sandbox, enabling OIDC-based authentication (e.g., for AWS federation). See the OIDC integration guide for more details.
• The new modal.Image.from_scratch() constructor creates an empty Image, equivalent to FROM scratch in Docker. This is primarily useful as a lightweight filesystem to mount into a Sandbox via modal.Sandbox.mount_image.
• The modal container list command now accepts an --app-id filter to return containers for a specific App.
• We’ve addressed an issue where modal.Sandbox.exec could hang if the Sandbox had terminated immediately after creation.
• An exception is now raised if the same Volume or CloudBucketMount is mounted at multiple paths in a container.
• The client will now error faster (≈60s) if it cannot establish an initial connection the Modal servers.

Finally, we are introducing a small number of breaking changes and enforcing some deprecations of pre-1.0 APIs:

• Exceptions returned by modal.Function.map() are no longer wrapped in a UserCodeException type, and we’re deprecating the transitional wrap_returned_exceptions= parameter.
• The modal.enable_output() context manager no longer yields a value; this had briefly leaked an internal type.
• We’ve removed unused namespace parameters from a number of APIs.
• It’s now required to pass -m on the CLI when using a module path spelling of the Function reference (e.g. modal deploy -m project.app )
• We’ve removed backwards compatibility for the old autoscaler configuration ( keep_warm , concurrency_limit , etc.).
• It’s no longer possible to look up a specific method on a Cls using modal.Function.from_name ; use modal.Cls.from_name instead.

• We’ve added a modal changelog CLI for retrieving changelog entries with a flexible query interface (e.g. modal changelog --since=1.2 , modal changelog --since=2025-12-01 , modal changelog --newer ). We expect that this will be a useful way to surface information about new features to coding agents.

• We’ve added a new modal.Secret.update method, which allows you to programmatically modify the environment variables within a Secret. This method has the semantics of Python’s dict.update : Secret contents can be overwritten or extended when using it. Note that Secret updates will take effect only for containers that start up after the modification.

• The dataclass returned by modal.Function.get_current_stats() now includes a num_running_inputs field that reports the number of inputs the Function is currently handling.

• We’re introducing “Directory Snapshots”: a new beta feature for persisting specific directories past the lifetime of an individual Sandbox. Using the new methods modal.Sandbox.snapshot_directory() and modal.Sandbox.mount_image(), you can capture the state of a directory and then later include it in a different Sandbox:

sb = modal.Sandbox.create(app=app)
snapshot = sb.snapshot_directory("/project")
sb2 = modal.Sandbox.create(app=app)
sb2.mount_image("/project", snapshot)

This feature can be useful for separating the lifecycle of application code in the Sandbox’s main Image from project code that changes in each Sandbox session. Files in the mounted snapshot also benefit from several optimizations that allow them to be read faster. See the Sandbox Snapshot guide for more information.

• We’ve added a new modal.Sandbox.detach() method that we recommend calling after you are done interacting with a Sandbox. This method disconnects your local client from the Sandbox and cleans up resources associated with the connection. After calling detach, operations on the Sandbox object may raise and are otherwise not guaranteed to work.

• The modal.Sandbox.terminate() method now accepts a wait parameter. With wait=True, terminate will block until the Sandbox is finished and return the exit code. The default wait=False maintains the previous behavior.

• Throughput for writing to the stdin of a modal.Sandbox.exec process has been increased by 8x.

• We’ve added a new modal.Volume.from_id() method for referencing a Volume by its object id.

• We’ve added a new modal billing report CLI and promoted the modal.billing.workspace_billing_report API to General Availability for all Team and Enterprise plan workspaces.
• We’ve added modal.Queue.from_id() and modal.Dict.from_id() methods to support referencing a Queue or Dict by its object id.
• Modal’s async usage warnings are now enabled by default. These warnings will fire when using a blocking interface on a Modal object in an async context. We’ve aimed to provide detailed and actionable suggestions for how to modify the code, which makes the warnings verbose. While we recommend addressing any warnings that pop up, as they can point to significant performance issues or bugs, we also provide a configuration option to disable them (MODAL_ASYNC_WARNINGS=0 or async_warnings = false in the .modal.toml). Please report any apparent false positives or incorrect suggested fixes.
• We’ve fixed a bug where the ASGI scope’s state contents could leak between requests when using @modal.asgi_app.

• Modal objects now have a .get_dashboard_url() method. This method will return a URL for viewing that object on the Modal dashboard:

  fc = f.spawn()
  print(fc.get_dashboard_url())
  # Easy access to logs, etc.
  

• There is also a new modal dashboard CLI and new modal app dashboard / modal volume dashboard CLI subcommands:

  • modal dashboard # Opens up the Apps homepage for the current environment
  • modal dashboard <object-id> # Opens up a view of this object
  • modal app dashboard <app-name> # Opens up the dashboard for this deployed App
  • modal volume dashboard <volume-name> # Opens up the file browser for this persistent Volume

• You can now pass a Sandbox ID (sb-xxxxx) directly to the modal container logs CLI.

• The modal token info CLI will now include the token name, if provided at token creation.

• We’ve fixed an issue where modal.Cls.with_options() (or the with_concurrency() / with_batching() methods) could sometimes use stale argument values when called repeatedly.

• We’ve improved our experimental support for Python 3.14t (free-threaded Python) inside Modal containers.

  • The container environment will now use the Python implementation of the Protobuf runtime rather than the incompatible upb implementation.

  • As 3.14t images are not being published to the official source for our prebuilt modal.Image.debian_slim() images, we recommend using modal.Image.from_registry to build a 3.14t Image:

    modal.Image.from_registry(
      "debian:bookworm-slim",
      add_python="3.14t"
    )
    

• Note that 3.14t support is available only on the 2025.06 Image Builder Version.

• Support is still experimental, so please share any issues that you encounter running 3.14t in Modal containers.

• It’s now possible to provide a custom_domain for a modal.Sandbox:

  sb = modal.Sandbox.create(..., custom_domain="sandboxes.mydomain.com")
  

  Note that Sandbox custom domains work differently from Function custom domains and must currently be set up manually by Modal; please get in touch if this feature interests you.

• We added a new modal token info CLI command to retrieve information about the credentials that are currently in use.

• We added a --timestamps flag to a number of CLI entrypoints (modal run, modal serve, modal deploy, and modal container logs) to show timestamps in the logging output.

• The automatic CLI creation for modal run entrypoints now supports Literal type annotations, provided that the literal type contains either all str or all int values.

• We’ve fixed a bug that could cause App builds to fail with an uninformative CancelledError when the App was misconfigured.

• We’ve improved client resource management when running modal.Sandbox.exec, which avoids a rare thread race condition.

Modal now supports Python 3.14. Python 3.14t (the free-threading build) support is currently a work in progress, because we are waiting for dependencies to be updated with free-threaded support. Additionally, Modal no longer supports Python 3.9, which has reached end-of-life.

We are adding experimental support for detecting cases where Modal’s blocking APIs are used in async contexts (which can be a source of bugs or performance issues). You can opt into runtime warnings by setting MODAL_ASYNC_WARNINGS=1 as an environment variable or async_warnings = true as a config field. We will enable these warnings by default in the future; please report any apparent false positives or other issues while support is experimental.

This release also includes a small number of deprecations and behavioral changes:

• The Modal SDK will no longer propagate grpclib.GRPCError types out to the user; our own modal.Error subtypes will be used instead. To avoid disrupting user code that has relied on GRPCError exceptions for control flow, we are temporarily making some exception types inherit from GRPCError so that they will also be caught by except grpclib.GRPCError statements. Accessing the .status attribute of the exception will issue a deprecation warning, but warnings cannot be issued if the exception object is only caught and there is no other interaction with it. We advise proactively migrating any exception handling to use Modal types, as we will remove the dependency on grpclib types entirely in the future. See the modal.exception docs for the mapping from gRPC status codes to Modal exception types.

• The max_inputs parameter in the @app.function() and @app.cls decorators has been renamed to single_use_containers and now takes a boolean value rather than an integer. Note that only max_inputs=1 has been supported, so this has no functional implications. This change is being made to reduce confusion with @modal.concurrent(max_inputs=...) and so that Modal’s autoscaler can provide better performance for Functions with single-use containers.

• The async (.aio) interface has been deprecated from modal.FunctionCall.from_id, modal.Image.from_id, and modal.SandboxSnapshot.from_id, because these methods do not perform I/O.

• The replace_bytes and delete_bytes methods have been removed from the modal.file_io filesystem interface.

• Images built with modal.Image.micromamba() using the 2023.12 Image Builder Version will now use a Python version that matches their local environment by default, rather than defaulting to Python 3.9.