Modal Web Serving

Use this skill when exposing Modal Functions as web endpoints, building APIs, or serving web applications.

For Servers (@app.server / modal.Server) — long-lived port-based HTTP with regional routing and default proxy-token auth — see modal-servers. For managed OpenAI-compatible LLM APIs, see modal-endpoints.

When to Use This Skill

• Creating REST/HTTP APIs from Modal Functions
• Serving ML model inference over HTTP
• Building web apps with FastAPI, Django, or Flask on Modal
• Setting up streaming (SSE) endpoints
• Configuring custom domains
• Adding authentication to web endpoints

Quick Start

image = modal.Image.debian_slim().pip_install("fastapi[standard]")

@app.function(image=image)
@modal.fastapi_endpoint()
def hello():
    return "Hello world!"

Deploy with modal serve (dev) or modal deploy (production).

Function Web Endpoints vs Servers vs Auto Endpoints

Modal has three related HTTP surfaces. Prefer Function web decorators for request/response APIs that fit the Function input model; migrate or start on Servers when latency and in-process concurrency matter; use Auto Endpoints for catalog/custom LLM inference without writing server code.

When to keep Function web endpoints

• Small FastAPI/ASGI/WSGI handlers with typed inputs and Modal’s input queue
• Existing middleware stacks already on @modal.asgi_app / @modal.wsgi_app
• Need Function orchestration (.remote(), .map(), retries/timeouts) more than raw HTTP latency
• Public URLs without proxy tokens (or optional requires_proxy_auth) are fine

When to migrate to Server (modal-servers)

• Serving a long-lived HTTP process (vLLM, custom uvicorn, raw http.server) where proxy latency matters
• Need routing_region / sticky Modal-Session-ID / target_concurrency autoscaling
• Want default authenticated ingress (proxy tokens) on *.modal.direct
• Replacing @modal.web_server — prefer @app.server (see modal-servers migration reference)

When to use Auto Endpoints (modal-endpoints)

• Production LLM chat completions against catalog or HF/Volume weights with minimal config
• Prefer managed recipes over custom @app.server / Function code

Auth and testing note

Servers and Auto Endpoints default to proxy-token auth (Modal-Key / Modal-Secret). Many Function web URLs are public unless you set requires_proxy_auth=True. For authenticated Server/Endpoint-style testing without pasting headers, use:

modal workspace proxy-tokens create
modal curl "https://<workspace>--<app>-<server>.<region>.modal.direct/path"

modal curl injects workspace proxy tokens (experimental; higher latency than raw curl with headers).

Four Ways to Serve HTTP

1. fastapi_endpoint (simplest)

Wraps a function in FastAPI automatically:

@app.function(image=image)
@modal.fastapi_endpoint()
def square(x: int):
    return {"square": x**2}

Accepts query params, POST bodies (dict or Pydantic models), path params.

2. asgi_app (full framework)

Serve a complete ASGI app (FastAPI, Starlette):

@app.function(image=image)
@modal.asgi_app()
def fastapi_app():
    from fastapi import FastAPI
    web_app = FastAPI()

    @web_app.get("/")
    def root():
        return {"message": "hello"}

    return web_app

3. wsgi_app (Django, Flask)

@app.function(image=image)
@modal.wsgi_app()
def flask_app():
    from flask import Flask
    app = Flask(__name__)

    @app.route("/")
    def root():
        return "hello"

    return app

4. web_server (raw HTTP)

For any HTTP server listening on a port:

@app.function(image=image)
@modal.web_server(port=8000)
def serve():
    import subprocess
    subprocess.Popen(["python", "-m", "http.server", "8000"])

For new low-latency port-based serving, prefer @app.server (modal-servers) over @modal.web_server.

Streaming Responses

Use FastAPI's StreamingResponse for SSE or chunked responses:

@app.function(image=image)
@modal.fastapi_endpoint()
def stream():
    from fastapi.responses import StreamingResponse

    def generate():
        for i in range(10):
            yield f"data: chunk {i}\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

Combine with .remote_gen() for GPU→web streaming:

@app.function(gpu="any")
def gpu_work():
    for chunk in process():
        yield chunk

@app.function(image=image)
@modal.fastapi_endpoint()
def endpoint():
    from fastapi.responses import StreamingResponse
    return StreamingResponse(gpu_work.remote_gen(), media_type="text/event-stream")

Authentication

Proxy auth (token-based)

@app.function()
@modal.fastapi_endpoint(requires_proxy_auth=True)
def secure_endpoint():
    return {"status": "authenticated"}

Requests must include Modal-Key and Modal-Secret headers (workspace proxy token). Same header shape as Servers/Endpoints; create tokens with modal workspace proxy-tokens create. For quick tests: modal curl <url>.

Custom domains

@app.function()
@modal.fastapi_endpoint(custom_domains=["api.example.com"])
def my_api():
    return {"hello": "world"}

Configure DNS CNAME to modal.run. SSL provisioned automatically.

Labels

Control the endpoint URL with label:

@modal.fastapi_endpoint(label="my-api")
# URL: https://<workspace>--my-api.modal.run

Timeouts

Web Function request timeout is 150 seconds by default. For long-running requests:

• Use streaming to keep the connection alive
• For >150s work, use .spawn() + polling pattern
• Webhooks have their own timeout configuration

Go/TypeScript SDK Note

Web endpoint definition (@modal.fastapi_endpoint, @modal.asgi_app, @modal.wsgi_app) is Python-only. The Go and TypeScript SDKs cannot define web endpoints.

However, you can call Functions backing web endpoints from Go/TS via fn.Remote() / fn.remote(). You can also create Sandboxes that run web servers internally (accessible via tunneled ports or within the Modal network).

Symptom Triage

"Endpoint returns 500"

• Inspect logs via modal-observability (modal app logs / modal container logs)
• Ensure FastAPI is installed in the image
• Verify Pydantic models match request schema

"Slow first request"

• Cold start; use min_containers=1 for warm containers
• Move model loading to @modal.enter() lifecycle hook

"Streaming not real-time"

• Use media_type="text/event-stream" for SSE
• Other content types may be buffered by the web server

"Request times out"

• Default web timeout is 150s; use streaming for long responses
• For heavy processing, use .spawn() + polling pattern

"401 on Server URL but Function URL works"

• Servers require proxy tokens by default; Function web URLs are often public
• Use modal curl or set Modal-Key / Modal-Secret; or unauthenticated=True on the Server

Reference Map

• references/web-endpoints.md — endpoint decorators, methods, POST/GET, Pydantic; vs Servers/Endpoints
• references/streaming-responses.md — SSE, StreamingResponse, async streaming
• references/custom-domains-auth.md — custom domains, authentication
• references/frameworks.md — FastAPI, Django, Flask integration patterns
• Sibling skills: modal-servers, modal-endpoints

Guardrails

• @modal.fastapi_endpoint requires FastAPI installed in the image
• Web Functions autoscale and scale to zero like regular Functions
• Use modal serve for development (live-reload), modal deploy for production
• @modal.web_endpoint is the old name; use @modal.fastapi_endpoint (v0.73.82+)
• requires_proxy_auth=True adds token-based auth; not a substitute for user auth
• Web request timeout is 150s — use streaming or async patterns for longer work
• Do not conflate Function web URLs (often public) with Server/Endpoint auth (proxy tokens by default)
• Prefer @app.server over new @modal.web_server for latency-sensitive port serving (modal-servers)