Modal logo
GuideReference

Overview

Introduction Example: Hello, world Tutorial: A simple web scraper

Custom container images

Custom container images Private registries

GPUs and other resources

GPU acceleration Reserving CPU and memory Example: Run a 40-billion parameter LLM (Falcon-40B)

Scaling out

Scaling out Example: Face detection on YouTube videos

Secrets and environment variables

Secrets Example: Write to Google Sheets

Deployment

Managing deployments Invoke deployed functions

Scheduling and cron jobs

Scheduling remote cron jobs Example: Hacker News Slackbot

Web endpoints

Web endpoints Streaming web endpoints Web endpoint URLs Request timeouts Example: Document OCR job queue Example: Document OCR web app

Sharing data

Passing local data Shared volumes

Deep learning and AI examples

Fast Stable diffusion Replace your CEO with an LLM Voice Chat with LLMs Parallel podcast transcription using Whisper Pet Art using Dreambooth Question-answering with LangChain Play with ControlNet Misc examples

Examples using popular libraries

DuckDB: Analyze NYC taxi data in parallel Blender: Distributed 3D rendering SQLite: Publish explorable data with Datasette Y! Finance: Stock prices in parallel

Reliability and robustness

Failures and retries Preemption Timeouts Troubleshooting

Security

Security at Modal

Other topics

Developing and debugging Cold start performance Workspaces Notebooks support Asynchronous usage Global variables Container lifecycle and parameters Apps, stubs, and entrypoints Useful snippets Example: Algolia docsearch crawler

Web endpoint URLs

User-specified URLs

Users have partial control over the URL of a web endpoint. For the web_endpoint, asgi_app and wsgi_app decorators, an optional label keyword argument can be provided, which allocates the URL https://<workspace>--<label>.modal.run for your endpoint.

For example, within a Modal workspace with slug my-workspace, the following code will deploy a webhook at the URL https://my-workspace--foo-bar.modal.run:

from modal import Stub, web_endpoint

stub = Stub(name="xyz")

@stub.function()
@web_endpoint(label="foo-bar")
def my_f():
    ...

Auto-generated URLs

If a label is not specified, web endpoints receive a generated URL under the modal.run domain. These generated URLs contain a subdomain label that is unique to the running endpoint.

Deployed apps

Web endpoints served by a deployed application have subdomains composed of the following parts:

  • Workspace name slug: ECorp → ecorp
  • App name slug: text_to_speech → text-to-speech
  • Function name slug: flask_app → flask-app

The deployed web endpoint URL for this example is https://ecorp--text-to-speech-flask-app.modal.run.

This URL is reserved for the deployed application’s web endpoint. Running the application during development will not replace the deployed application’s association with the deployed URL.

Ephemeral apps

Web endpoints run in ephemeral apps have predictable, unique subdomains, distinct from the subdomain of any associated deployment.

The subdomain of a web endpoint running in an ephemeral app is composed of the following parts:

  • Workspace name slug: ECorp → ecorp
  • App name slug: text_to_speech → text-to-speech
  • Function name slug: flask_app → flask-app
  • [Optional] Member name slug, in cases where app runs in a shared workspace: erikbern
  • [Optional] An instance identifier, ensuring uniqueness in the presence of concurrent ephemeral app runs: 1234abcd
  • A -dev suffix, calling out that this web endpoint is not deployed.

Combining the example parts, the ephemeral web endpoint’s URL could be https://ecorp--text-to-speech-flask-app-erikbern-1234abcd-dev.modal.run.

The components of an ephemeral web endpoint subdomain ensure URL predictability during development and testing, in both personal and shared workspaces. Multiple copies of a web endpoint can be active when a Modal app is run in two or more terminal windows, or when multiple developers are iterating on the same application codebase. Every copy will be uniquely addressable while running.

Stealing

If an emphemeral web endpoint is running and another ephemeral web endpoint is created seeking the same web endpoint label, the new web endpoint function will steal the running web endpoint’s label.

This ensures the latest iteration of an ephemeral web endpoint function is serving requests, while older ones stop recieving web traffic.

(Previously concurrently running ephemeral app web endpoints would include conflict-avoiding hashes.)

Truncation

If a generated subdomain label is longer than 63 characters, it will be truncated.

For example, the following subdomain label is too long, 67 characters: ecorp--text-to-speech-really-really-long-function-name-erikbern-dev.

The truncation happens by calculating a SHA-256 hash of the overlong label, then taking the first 6 characters of this hash. The overlong subdomain label is truncated to 56 characters, and then joined by a dash to the hash prefix.

The combination of the label hashing and truncation provides a unique list of 63 characters, complying with both DNS system limits and uniqueness requirements.