# Guide

This page is a high-level guide to Modal Workspaces, the primary unit of organization for Modal resources and authentication. This guide explains how to set up Web Functions with Modal. This guide documents the behavior of URLs for Web Functions on Modal: automatic generation, configuration,...

## Pages in this folder

| Page | Local file | Summary |
| --- | --- | --- |
| Workspaces \| Modal Docs | [workspaces-modal-docs.md](workspaces-modal-docs.md) | This page is a high-level guide to Modal Workspaces, the primary unit of organization for Modal resources and authentication. |
| Web Functions \| Modal Docs | [web-functions-modal-docs.md](web-functions-modal-docs.md) | This guide explains how to set up Web Functions with Modal. |
| Web Function URLs \| Modal Docs | [web-function-urls-modal-docs.md](web-function-urls-modal-docs.md) | This guide documents the behavior of URLs for Web Functions on Modal: automatic generation, configuration, programmatic retrieval, and more. |
| Volumes \| Modal Docs | [volumes-modal-docs.md](volumes-modal-docs.md) | Volumes are a high-performance distributed file system for Modal applications. They are optimized for write-once, read-many I/O workloads, like creating machine learning model weights and distributing them for inference. |
| VM Sandboxes \| Modal Docs | [vm-sandboxes-modal-docs.md](vm-sandboxes-modal-docs.md) | Run Modal Sandboxes on a full VM with a real Linux kernel |
| Using OIDC to authenticate with external services \| Modal Docs | [using-oidc-to-authenticate-with-external-services-modal-docs.md](using-oidc-to-authenticate-with-external-services-modal-docs.md) | Authenticate Modal Functions with AWS, GCP, and other services using OIDC tokens instead of storing long-lived credentials. |
| Using existing images \| Modal Docs | [using-existing-images-modal-docs.md](using-existing-images-modal-docs.md) | This guide walks you through how to use an existing container image as a Modal Image. |
| Using CUDA on Modal \| Modal Docs | [using-cuda-on-modal-modal-docs.md](using-cuda-on-modal-modal-docs.md) | Modal makes it easy to accelerate your workloads with datacenter-grade NVIDIA GPUs. |
| Use Modal Dicts and Queues together \| Modal Docs | [use-modal-dicts-and-queues-together-modal-docs.md](use-modal-dicts-and-queues-together-modal-docs.md) | Modal Dicts and Queues store and communicate objects in distributed applications on Modal. |
| Tunnels \| Modal Docs | [tunnels-modal-docs.md](tunnels-modal-docs.md) | Modal allows you to expose live TCP ports on a Modal container. This is done by creating a tunnel that forwards the port to the public Internet. |
| Troubleshooting \| Modal Docs | [troubleshooting-modal-docs.md](troubleshooting-modal-docs.md) | This guide page documents solutions for common Modal issues. |
| Timeouts \| Modal Docs | [timeouts-modal-docs.md](timeouts-modal-docs.md) | All Modal Function executions have a default execution timeout of 300 seconds (5 minutes), but users may specify timeout durations between 1 second and 24 hours. |
| Streaming endpoints \| Modal Docs | [streaming-endpoints-modal-docs.md](streaming-endpoints-modal-docs.md) | Modal fastapi_endpoints support streaming responses using FastAPI’s StreamingResponse class. This class accepts asynchronous generators, synchronous generators, or any Python object that implements the iterator protocol, and can be used with Modal Functions! |
| Storing model weights on Modal \| Modal Docs | [storing-model-weights-on-modal-modal-docs.md](storing-model-weights-on-modal-modal-docs.md) | Efficiently managing the weights of large models is crucial for optimizing the build times and startup latency of many ML and AI applications. |
| Snapshots \| Modal Docs | [snapshots-modal-docs.md](snapshots-modal-docs.md) | Sandboxes support snapshotting, allowing you to save your Sandbox’s state and restore it later. This is useful for: |
| Slack notifications \| Modal Docs | [slack-notifications-modal-docs.md](slack-notifications-modal-docs.md) | Integrate your Modal Workspace with Slack to receive timely essential notifications |
| Service Users \| Modal Docs | [service-users-modal-docs.md](service-users-modal-docs.md) | Service users are programmatic accounts that allow automated systems to interact with Modal. They’re ideal for CI/CD pipelines, automated deployments, and other workflows that need to authenticate. |
| Servers \| Modal Docs | [servers-modal-docs.md](servers-modal-docs.md) | Modal Servers are a serverless compute primitive optimized for low-latency HTTP communication between external clients and a process running in a container on Modal. |
| Security and privacy at Modal \| Modal Docs | [security-and-privacy-at-modal-modal-docs.md](security-and-privacy-at-modal-modal-docs.md) | The document outlines Modal’s security and privacy commitments. |
| Secrets \| Modal Docs | [secrets-modal-docs.md](secrets-modal-docs.md) | Securely provide credentials and other sensitive information to your Modal Functions with Secrets. |
| Scheduling remote cron jobs \| Modal Docs | [scheduling-remote-cron-jobs-modal-docs.md](scheduling-remote-cron-jobs-modal-docs.md) | A common requirement is to perform some task at a given time every day or week automatically. Modal facilitates this through function schedules. |
| Scaling out \| Modal Docs | [scaling-out-modal-docs.md](scaling-out-modal-docs.md) | Modal makes it trivially easy to scale compute across thousands of containers. You won’t have to worry about your App crashing if it goes viral or need to wait a long time for your batch jobs to complete. |
| Sandboxes \| Modal Docs | [sandboxes-modal-docs.md](sandboxes-modal-docs.md) | This page is a high-level guide to Sandboxes, secure containers for executing untrusted user or agent code on Modal. |
| Sandboxes \| Modal Docs | [sandboxes-modal-docs-2.md](sandboxes-modal-docs-2.md) | This page is a high-level guide to Sandboxes, secure containers for executing untrusted user or agent code on Modal. |
| Sandbox resources and pricing \| Modal Docs | [sandbox-resources-and-pricing-modal-docs.md](sandbox-resources-and-pricing-modal-docs.md) | Configure CPU, memory, and other resources for Modal Sandboxes. Modal's usage based pricing and ability to burst beyond requests enable cost-efficient resource allocation. |
| S3 Gateway endpoints \| Modal Docs | [s3-gateway-endpoints-modal-docs.md](s3-gateway-endpoints-modal-docs.md) | When running workloads in AWS, our system automatically uses a corresponding S3 Gateway endpoint to ensure low costs, optimal performance, and network reliability between Modal and S3. |
| Running commands in Sandboxes \| Modal Docs | [running-commands-in-sandboxes-modal-docs.md](running-commands-in-sandboxes-modal-docs.md) | Once you have created a Sandbox, you can run commands inside it using the Sandbox.exec method. |
| Run untrusted code with Restricted Functions \| Modal Docs | [run-untrusted-code-with-restricted-functions-modal-docs.md](run-untrusted-code-with-restricted-functions-modal-docs.md) | This guide page documents Restricted Functions, which can be used to safely execute untrusted code in Modal Functions. |
| Role-Based Access Control (RBAC) \| Modal Docs | [role-based-access-control-rbac-modal-docs.md](role-based-access-control-rbac-modal-docs.md) | Control access to Modal Workspaces, Environments, and Web Functions with role-based permissions for Owners, Managers, and Members. |
| Request timeouts \| Modal Docs | [request-timeouts-modal-docs.md](request-timeouts-modal-docs.md) | Handle long-running Web Function requests on Modal with automatic redirects and polling patterns for results. |
| Region selection \| Modal Docs | [region-selection-modal-docs.md](region-selection-modal-docs.md) | Modal runs containers globally across multiple different clouds. By default, all inputs to Modal Functions are routed through our servers in Virginia, USA (us-east) before being sent to a container for execution. |
| Queues \| Modal Docs | [queues-modal-docs.md](queues-modal-docs.md) | Modal Queues provide distributed FIFO queues to your Modal Apps. |
| Proxy Tokens \| Modal Docs | [proxy-tokens-modal-docs.md](proxy-tokens-modal-docs.md) | Use Proxy Tokens to prevent unauthorized clients from triggering your Web Functions. |
| Proxies \| Modal Docs | [proxies-modal-docs.md](proxies-modal-docs.md) | Securely connect with your private resources from Modal containers |
| Project structure \| Modal Docs | [project-structure-modal-docs.md](project-structure-modal-docs.md) | Structure Modal projects across multiple files using Python packages and module mode for clean, maintainable code. |
| Preemption \| Modal Docs | [preemption-modal-docs.md](preemption-modal-docs.md) | All Modal Functions are subject to preemption by default. If a preemption event interrupts a running Function, Modal will gracefully terminate the Function and restart it on the same input. |
| Passing local data \| Modal Docs | [passing-local-data-modal-docs.md](passing-local-data-modal-docs.md) | If you have a function that needs access to some data not present in your Python files themselves you have a few options for bundling that data with your Modal App. |
| Parametrized functions \| Modal Docs | [parametrized-functions-modal-docs.md](parametrized-functions-modal-docs.md) | A single Modal Function can be parametrized by a set of arguments, so that each unique combination of arguments will behave like an individual Modal Function with its own auto-scaling and lifecycle logic. |
| Parametrized functions \| Modal Docs | [parametrized-functions-modal-docs-2.md](parametrized-functions-modal-docs-2.md) | A single Modal Function can be parametrized by a set of arguments, so that each unique combination of arguments will behave like an individual Modal Function with its own auto-scaling and lifecycle logic. |
| Okta SSO \| Modal Docs | [okta-sso-modal-docs.md](okta-sso-modal-docs.md) | Configure Okta Single Sign-On for your Modal Workspace with IdP-initiated SSO and just-in-time account provisioning. |
| Networking and security \| Modal Docs | [networking-and-security-modal-docs.md](networking-and-security-modal-docs.md) | Sandboxes are built to be secure-by-default, meaning that a default Sandbox has no ability to accept incoming network connections or access your Modal resources. |
| Named images \| Modal Docs | [named-images-modal-docs.md](named-images-modal-docs.md) | Named Images let you publish a Modal Image under a name that you can reference later to use the Image, akin to a container registry. |
| Multi-node clusters \| Modal Docs | [multi-node-clusters-modal-docs.md](multi-node-clusters-modal-docs.md) | Train and serve very large models with Modal's multi-node clusters. |
| Modal user account setup \| Modal Docs | [modal-user-account-setup-modal-docs.md](modal-user-account-setup-modal-docs.md) | To run and deploy applications on Modal you’ll need to sign up and create a user account. |
| Modal SDKs for JavaScript and Go \| Modal Docs | [modal-sdks-for-javascript-and-go-modal-docs.md](modal-sdks-for-javascript-and-go-modal-docs.md) | Interact with Modal Sandboxes and call deployed Modal Functions from JS and Go codebases |
| Modal Notebooks \| Modal Docs | [modal-notebooks-modal-docs.md](modal-notebooks-modal-docs.md) | Notebooks allow you to write and execute Python code in Modal’s cloud, within your browser. It’s a hosted Jupyter notebook with: |
| Modal Notebooks \| Modal Docs | [modal-notebooks-modal-docs-2.md](modal-notebooks-modal-docs-2.md) | Notebooks allow you to write and execute Python code in Modal’s cloud, within your browser. It’s a hosted Jupyter notebook with: |
| Modal 1.0 migration guide \| Modal Docs | [modal-1-0-migration-guide-modal-docs.md](modal-1-0-migration-guide-modal-docs.md) | We released version 1.0 of the Modal Python SDK in May 2025. This release signifies an increased commitment to API stability and implies some changes to our development workflow. |
| Memory Snapshots \| Modal Docs | [memory-snapshots-modal-docs.md](memory-snapshots-modal-docs.md) | Modal Memory Snapshots can dramatically reduce the cold start latency of Modal Functions by skipping initialization work on most container boots. |
| Memory Snapshots \| Modal Docs | [memory-snapshots-modal-docs-2.md](memory-snapshots-modal-docs-2.md) | Modal Memory Snapshots can dramatically reduce the cold start latency of Modal Functions by skipping initialization work on most container boots. |
| Managing deployments \| Modal Docs | [managing-deployments-modal-docs.md](managing-deployments-modal-docs.md) | Once you’ve finished using modal run or modal serve to iterate on your Modal code, it’s time to deploy. A Modal deployment creates and then persists an App and its objects, providing the following benefits: |
| Large dataset ingestion \| Modal Docs | [large-dataset-ingestion-modal-docs.md](large-dataset-ingestion-modal-docs.md) | This guide provides best practices for downloading, transforming, and storing large datasets within Modal. A dataset is considered large if it contains hundreds of thousands of files and/or is over 100 GiB in size. |
| Jupyter notebooks \| Modal Docs | [jupyter-notebooks-modal-docs.md](jupyter-notebooks-modal-docs.md) | This guide page documents integrations between Jupyter notebooks and Modal. |
| Job processing \| Modal Docs | [job-processing-modal-docs.md](job-processing-modal-docs.md) | Modal can be used as a scalable job queue to handle asynchronous tasks submitted from a web app or any other Python application. This allows you to offload up to 1 million long-running or resource-intensive tasks to Modal, while your main application remains responsive. |
| Invoking deployed Functions \| Modal Docs | [invoking-deployed-functions-modal-docs.md](invoking-deployed-functions-modal-docs.md) | Modal lets you take a Function created by a deployment and call it from other contexts. |
| Introduction \| Modal Docs | [introduction-modal-docs.md](introduction-modal-docs.md) | Modal is a serverless AI infrastructure platform with sub-second cold starts and per-second pricing. |
| Input concurrency \| Modal Docs | [input-concurrency-modal-docs.md](input-concurrency-modal-docs.md) | This guide documents the use of the modal.concurrent decorator to process multiple inputs at the same time in a single Modal container. |
| Images \| Modal Docs | [images-modal-docs.md](images-modal-docs.md) | This guide walks you through how to define a Modal Image, the environment your Modal code runs in. |
| Images \| Modal Docs | [images-modal-docs-2.md](images-modal-docs-2.md) | This guide walks you through how to define a Modal Image, the environment your Modal code runs in. |
| High-performance LLM inference \| Modal Docs | [high-performance-llm-inference-modal-docs.md](high-performance-llm-inference-modal-docs.md) | This high-level guide documents the key techniques used to achieve high performance when running LLM inference on Modal. |
| GPU Metrics \| Modal Docs | [gpu-metrics-modal-docs.md](gpu-metrics-modal-docs.md) | Modal exposes a number of GPU metrics that help monitor the health and utilization of the GPUs you’re using. |
| GPU Health \| Modal Docs | [gpu-health-modal-docs.md](gpu-health-modal-docs.md) | Modal constantly monitors host GPU health, draining Workers with critical issues and surfacing warnings for customer triage. |
| GPU acceleration \| Modal Docs | [gpu-acceleration-modal-docs.md](gpu-acceleration-modal-docs.md) | Modal makes it easy to run your code on GPUs. |
| Global variables \| Modal Docs | [global-variables-modal-docs.md](global-variables-modal-docs.md) | Handle global variables and data in Modal Functions using modal.is_local to differentiate local and cloud execution. |
| Filesystem Access \| Modal Docs | [filesystem-access-modal-docs.md](filesystem-access-modal-docs.md) | There are multiple options for uploading files to a Sandbox and accessing them from outside the Sandbox. |
| Feature Maturity \| Modal Docs | [feature-maturity-modal-docs.md](feature-maturity-modal-docs.md) | New features at Modal evolve through several stages. To help you understand their stability, we use two separate concepts: |
| Fast pull from registry \| Modal Docs | [fast-pull-from-registry-modal-docs.md](fast-pull-from-registry-modal-docs.md) | The performance of pulling public and private images from registries into Modal can be significantly improved by adopting the eStargz compression format. |
| Failures and retries \| Modal Docs | [failures-and-retries-modal-docs.md](failures-and-retries-modal-docs.md) | Failure is part of life. Sometimes you just have to retry. This guide page documents how to do this on Modal. |
| Environments \| Modal Docs | [environments-modal-docs.md](environments-modal-docs.md) | Modal Environments isolate Modal applications and resources from one another. |
| Environment variables \| Modal Docs | [environment-variables-modal-docs.md](environment-variables-modal-docs.md) | The Modal runtime sets several environment variables during initialization. The keys for these environment variables are reserved and cannot be overridden by your Function or Sandbox configuration. |
| Endpoints \| Modal Docs | [endpoints-modal-docs.md](endpoints-modal-docs.md) | Deploy a production-ready LLM inference endpoint on Modal’s managed infrastructure with a single command: |
| Endpoint metrics \| Modal Docs | [endpoint-metrics-modal-docs.md](endpoint-metrics-modal-docs.md) | Every endpoint reports live inference metrics so you can see how it’s performing under real traffic — latency, throughput, and how many requests are in flight. Open an endpoint from the Endpoints tab and go to the Activity view to see them. |
| Dynamic Function configuration \| Modal Docs | [dynamic-function-configuration-modal-docs.md](dynamic-function-configuration-modal-docs.md) | Many aspects of a Modal Function’s configuration can be dynamically configured from a specific call site. This is useful in cases where the Function’s compute resources, secrets, timeout, or other properties need to vary depending on the specific inputs. |
| Dynamic batching \| Modal Docs | [dynamic-batching-modal-docs.md](dynamic-batching-modal-docs.md) | Modal’s @batched feature allows you to accumulate requests and process them in dynamically-sized batches, rather than one-by-one. |
| Dicts \| Modal Docs | [dicts-modal-docs.md](dicts-modal-docs.md) | Modal Dicts provide distributed key-value storage to your Modal Apps. |
| Developing and debugging \| Modal Docs | [developing-and-debugging-modal-docs.md](developing-and-debugging-modal-docs.md) | Modal makes it easy to run apps in the cloud, try code changes in the cloud, and debug remotely executing code as if it were right there on your laptop. To speed boost your inner dev loop, this guide provides a rundown of tools and techniques for developing and debugging software in Modal. |
| Customer Supplied Encryption Keys \| Modal Docs | [customer-supplied-encryption-keys-modal-docs.md](customer-supplied-encryption-keys-modal-docs.md) | Use Customer Supplied Encryption Keys to protect supported Modal resources with key material that Modal does not store. |
| Custom SAML SSO \| Modal Docs | [custom-saml-sso-modal-docs.md](custom-saml-sso-modal-docs.md) | Configure custom SAML Single Sign-On for your Modal Workspace with any identity provider. |
| Continuous deployment \| Modal Docs | [continuous-deployment-modal-docs.md](continuous-deployment-modal-docs.md) | It’s a common pattern to auto-deploy your Modal App as part of a CI/CD pipeline. To get you started, below is a guide to doing continuous deployment of a Modal App in GitHub. |
| Container lifecycle hooks \| Modal Docs | [container-lifecycle-hooks-modal-docs.md](container-lifecycle-hooks-modal-docs.md) | Since Modal will reuse the same container for multiple inputs, sometimes you might want to run some code exactly once when the container starts or exits. |
| Connecting Modal to your OpenTelemetry Provider \| Modal Docs | [connecting-modal-to-your-opentelemetry-provider-modal-docs.md](connecting-modal-to-your-opentelemetry-provider-modal-docs.md) | You can export Modal logs to your OpenTelemetry provider using the Modal OpenTelemetry integration. This integration is compatible with any observability provider that supports the OpenTelemetry HTTP APIs. |
| Connecting Modal to your Datadog account \| Modal Docs | [connecting-modal-to-your-datadog-account-modal-docs.md](connecting-modal-to-your-datadog-account-modal-docs.md) | You can use the Modal + Datadog Integration to export Modal Function logs to Datadog. You’ll find the Modal Datadog Integration available for install in the Datadog marketplace. |
| Configuring CPU, memory, and disk \| Modal Docs | [configuring-cpu-memory-and-disk-modal-docs.md](configuring-cpu-memory-and-disk-modal-docs.md) | Request specific CPU cores and memory for Modal containers. Configure resource limits for compute-intensive workloads. |
| Cold start performance \| Modal Docs | [cold-start-performance-modal-docs.md](cold-start-performance-modal-docs.md) | This guide page details the techniques and Modal features used to improve cold start performance. |
| Cluster networking \| Modal Docs | [cluster-networking-modal-docs.md](cluster-networking-modal-docs.md) | Enable low-latency, high-bandwidth (50+ Gbps) private networking between Modal containers for distributed workloads. |
| Cloud bucket mounts \| Modal Docs | [cloud-bucket-mounts-modal-docs.md](cloud-bucket-mounts-modal-docs.md) | The modal.CloudBucketMount is a mutable volume that allows for both reading and writing files from a cloud bucket. It supports AWS S3, Cloudflare R2, and Google Cloud Storage buckets. |
| Budgets \| Modal Docs | [budgets-modal-docs.md](budgets-modal-docs.md) | Modal budgets let you cap spend at both the Workspace and Environment level: |
| Billing \| Modal Docs | [billing-modal-docs.md](billing-modal-docs.md) | Modal is serverless, which means you only pay for the compute you use or request. Reservations are not required, and there are no minimum usage-time increments. Up-to-date unit pricing for all of our products is available on our Pricing page. |
| Benchmark an endpoint \| Modal Docs | [benchmark-an-endpoint-modal-docs.md](benchmark-an-endpoint-modal-docs.md) | Live metrics tell you how an endpoint behaves under whatever traffic it happens to be getting. A benchmark tells you how it behaves under a known, repeatable load — so you can compare models, regions, and configurations on an apples-to-apples basis. |
| Batch Processing \| Modal Docs | [batch-processing-modal-docs.md](batch-processing-modal-docs.md) | Modal is optimized for large-scale batch processing, allowing functions to scale to thousands of parallel containers with zero additional configuration. Function calls can be submitted asynchronously for background execution, eliminating the need to wait for jobs to finish or tune resource allocation. |
| Audit Logs \| Modal Docs | [audit-logs-modal-docs.md](audit-logs-modal-docs.md) | Audit logs give your workspace an append-only record of the sensitive actions that change its state — who did what, when, to which resource, and from where. They are designed for compliance reviews, incident investigation, and answering questions like “did anyone delete this Secret last Thursday?” without asking Modal support. |
| Asynchronous API usage \| Modal Docs | [asynchronous-api-usage-modal-docs.md](asynchronous-api-usage-modal-docs.md) | All of the functions in Modal are available in both standard (blocking) and asynchronous variants. The async interface can be accessed by appending .aio to any function in the Modal API. |
| Apps, Functions, and entrypoints \| Modal Docs | [apps-functions-and-entrypoints-modal-docs.md](apps-functions-and-entrypoints-modal-docs.md) | An App represents an application running on Modal. It groups one or more Functions for atomic deployment and acts as a shared namespace. All Functions and Clses are associated with an App. |