modal

# Modal

## Overview

Modal is a cloud platform for running Python code serverlessly, with a focus on AI/ML workloads. Key capabilities:
- **GPU compute** on demand (T4, L4, A10, L40S, A100, H100, H200, B200)
- **Serverless functions** with autoscaling from zero to thousands of containers
- **Custom container images** built entirely in Python code
- **Persistent storage** via Volumes for model weights and datasets
- **Web endpoints** for serving models and APIs
- **Scheduled jobs** via cron or fixed intervals
- **Sub-second cold starts** for low-latency inference

Everything in Modal is defined as code — no YAML, no Dockerfiles required (though both are supported).

## When to Use This Skill

Use this skill when:
- Deploy or serve AI/ML models in the cloud
- Run GPU-accelerated computations (training, inference, fine-tuning)
- Create serverless web APIs or endpoints
- Scale batch processing jobs in parallel
- Schedule recurring tasks (data pipelines, retraining, scraping)
- Need persistent cloud storage for model weights or datasets
- Want to run code in custom container environments
- Build job queues or async task processing systems

## Installation and Authentication

### Install

```bash
uv pip install modal
```

### Authenticate

Prefer existing credentials before creating new ones:

1. Check whether `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` are already present in the current environment.
2. If not, check for those values in a local `.env` file and load them if appropriate for the workflow.
3. Only fall back to interactive `modal setup` or generating fresh tokens if neither source already provides credentials.

```bash
modal setup
```

This opens a browser for authentication. For CI/CD or headless environments, use environment variables:

```bash
export MODAL_TOKEN_ID=<your-token-id>
export MODAL_TOKEN_SECRET=<your-token-secret>
```

If tokens are not already available in the environment or `.env`, generate them at https://modal.com/settings

Modal offers a free tier with $30/month in credits.

**Reference**: See `references/getting-started.md` for detailed setup and first app walkthrough.

## Core Concepts

### App and Functions

A Modal `App` groups related functions. Functions decorated with `@app.function()` run remotely in the cloud:

```python
import modal

app = modal.App("my-app")

@app.function()
def square(x):
    return x ** 2

@app.local_entrypoint()
def main():
    # .remote() runs in the cloud
    print(square.remote(42))
```

Run with `modal run script.py`. Deploy with `modal deploy script.py`.

**Reference**: See `references/functions.md` for lifecycle hooks, classes, `.map()`, `.spawn()`, and more.

### Container Images

Modal builds container images from Python code. The recommended package installer is `uv`:

```python
image = (
    modal.Image.debian_slim(python_version="3.11")
    .uv_pip_install("torch==2.8.0", "transformers", "accelerate")
    .apt_install("git")
)

@app.function(image=image)
def inference(prompt):
    from transformers import pipeline
    pipe = pipeline("text-generation", model="meta-llama/Llama-3-8B")
    return pipe(prompt)
```

Key image methods:
- `.uv_pip_install()` — Install Python packages with uv (recommended)
- `.pip_install()` — Install with pip (fallback)
- `.apt_install()` — Install system packages
- `.run_commands()` — Run shell commands during build
- `.run_function()` — Run Python during build (e.g., download model weights)
- `.add_local_python_source()` — Add local modules
- `.env()` — Set environment variables

**Reference**: See `references/images.md` for Dockerfiles, micromamba, caching, GPU build steps.

### GPU Compute

Request GPUs via the `gpu` parameter:

```python
@app.function(gpu="H100")
def train_model():
    import torch
    device = torch.device("cuda")
    # GPU training code here

# Multiple GPUs
@app.function(gpu="H100:4")
def distributed_training():
    ...

# GPU fallback chain
@app.function(gpu=["H100", "A100-80GB", "A100-40GB"])
def flexible_inference():
    ...
```

Available GPUs: T4, L4, A10, L40S, A100-40GB, A100-80GB, H100, H200, B200, B200+

- Up to 8 GPUs per container (except A10: up to 4)
- L40S is recommended for inference (cost/performance balance, 48 GB VRAM)
- H100/A100 can be auto-upgraded to H200/A100-80GB at no extra cost
- Use `gpu="H100!"` to prevent auto-upgrade

**Reference**: See `references/gpu.md` for GPU selection guidance and multi-GPU training.

### Volumes (Persistent Storage)

Volumes provide distributed, persistent file storage:

```python
vol = modal.Volume.from_name("model-weights", create_if_missing=True)

@app.function(volumes={"/data": vol})
def save_model():
    # Write to the mounted path
    with open("/data/model.pt", "wb") as f:
        torch.save(model.state_dict(), f)

@app.function(volumes={"/data": vol})
def load_model():
    model.load_state_dict(torch.load("/data/model.pt"))
```

- Optimized for write-once, read-many workloads (model weights, datasets)
- CLI access: `modal volume ls`, `modal volume put`, `modal volume get`
- Background auto-commits every few seconds

**Reference**: See `references/volumes.md` for v2 volumes, concurrent writes, and best practices.

### Secrets

Securely pass credentials to functions:

```python
@app.function(secrets=[modal.Secret.from_name("my-api-keys")])
def call_api():
    import os
    api_key = os.environ["API_KEY"]
    # Use the key
```

Create secrets via CLI: `modal secret create my-api-keys API_KEY=sk-xxx`

Or from a `.env` file: `modal.Secret.from_dotenv()`

**Reference**: See `references/secrets.md` for dashboard setup, multiple secrets, and templates.

### Web Endpoints

Serve models and APIs as web endpoints:

```python
@app.function()
@modal.fastapi_endpoint()
def predict(text: str):
    return {"result": model.predict(text)}
```

- `modal serve script.py` — Development with hot reload and temporary URL
- `modal deploy script.py` — Production deployment with permanent URL
- Supports FastAPI, ASGI (Starlette, FastHTML), WSGI (Flask, Django), WebSockets
- Request bodies up to 4 GiB, unlimited response size

**Reference**: See `references/web-endpoints.md` for ASGI/WSGI apps, streaming, auth, and WebSockets.

### Scheduled Jobs

Run functions on a schedule:

```python
@app.function(schedule=modal.Cron("0 9 * * *"))  # Daily at 9 AM UTC
def daily_pipeline():
    # ETL, retraining, scraping, etc.
    ...

@app.function(schedule=modal.Period(hours=6))
def periodic_check():
    ...
```

Deploy with `modal deploy script.py` to activate the schedule.

- `modal.Cron("...")` — Standard cron syntax, stable across deploys
- `modal.Period(hours=N)` — Fixed interval, resets on redeploy
- Monitor runs in the Modal dashboard

**Reference**: See `references/scheduled-jobs.md` for cron syntax and management.

### Scaling and Concurrency

Modal autoscales containers automatically. Configure limits:

```python
@app.function(
    max_containers=100,    # Upper limit
    min_containers=2,      # Keep warm for low latency
    buffer_containers=5,   # Reserve capacity
    scaledown_window=300,  # Idle seconds before shutdown
)
def process(data):
    ...
```

Process inputs in parallel with `.map()`:

```python
results = list(process.map([item1, item2, item3, ...]))
```

Enable concurrent request handling per container:

```python
@app.function()
@modal.concurrent(max_inputs=10)
async def handle_request(req):
    ...
```

**Reference**: See `references/scaling.md` for `.map()`, `.starmap()`, `.spawn()`, and limits.

### Resource Configuration

```python
@app.function(
    cpu=4.0,              # Physical cores (not vCPUs)
    memory=16384,         # MiB
    ephemeral_disk=51200, # MiB (up to 3 TiB)
    timeout=3600,         # Seconds
)
def heavy_computation():
    ...
```

Defaults: 0.125 CPU cores, 128 MiB memory. Billed on max(request, usage).

**Reference**: See `references/resources.md` for limits and billing details.

## Classes with Lifecycle Hooks

For stateful workloads (e.g., loading a model once and serving many requests):

```python
@app.cls(gpu="L40S", image=image)
class Predictor:
    @modal.enter()
    def load_model(self):
        self.model = load_heavy_model()  # Runs once on container start

    @modal.method()
    def predict(self, text: str):
        return self.model(text)

    @modal.exit()
    def cleanup(self):
        ...  # Runs on container shutdown
```

Call with: `Predictor().predict.remote("hello")`

## Common Workflow Patterns

### GPU Model Inference Service

```python
import modal

app = modal.App("llm-service")

image = (
    modal.Image.debian_slim(python_version="3.11")
    .uv_pip_install("vllm")
)

@app.cls(gpu="H100", image=image, min_containers=1)
class LLMService:
    @modal.enter()
    def load(self):
        from vllm import LLM
        self.llm = LLM(model="meta-llama/Llama-3-70B")

    @modal.method()
    @modal.fastapi_endpoint(method="POST")
    def generate(self, prompt: str, max_tokens: int = 256):
        outputs = self.llm.generate([prompt], max_tokens=max_tokens)
        return {"text": outputs[0].outputs[0].text}
```

### Batch Processing Pipeline

```python
app = modal.App("batch-pipeline")
vol = modal.Volume.from_name("pipeline-data", create_if_missing=True)

@app.function(volumes={"/data": vol}, cpu=4.0, memory=8192)
def process_chunk(chunk_id: int):
    import pandas as pd
    df = pd.read_parquet(f"/data/input/chunk_{chunk_id}.parquet")
    result = heavy_transform(df)
    result.to_parquet(f"/data/output/chunk_{chunk_id}.parquet")
    return len(result)

@app.local_entrypoint()
def main():
    chunk_ids = list(range(100))
    results = list(process_chunk.map(chunk_ids))
    print(f"Processed {sum(results)} total rows")
```

### Scheduled Data Pipeline

```python
app = modal.App("etl-pipeline")

@app.function(
    schedule=modal.Cron("0 */6 * * *"),  # Every 6 hours
    secrets=[modal.Secret.from_name("db-credentials")],
)
def etl_job():
    import os
    db_url = os.environ["DATABASE_URL"]
    # Extract, transform, load
    ...
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `modal setup` | Authenticate with Modal |
| `modal run script.py` | Run a script's local entrypoint |
| `modal serve script.py` | Dev server with hot reload |
| `modal deploy script.py` | Deploy to production |
| `modal volume ls <name>` | List files in a volume |
| `modal volume put <name> <file>` | Upload file to volume |
| `modal volume get <name> <file>` | Download file from volume |
| `modal secret create <name> K=V` | Create a secret |
| `modal secret list` | List secrets |
| `modal app list` | List deployed apps |
| `modal app stop <name>` | Stop a deployed app |

## Reference Files

Detailed documentation for each topic:

- `references/getting-started.md` — Installation, authentication, first app
- `references/functions.md` — Functions, classes, lifecycle hooks, remote execution
- `references/images.md` — Container images, package installation, caching
- `references/gpu.md` — GPU types, selection, multi-GPU, training
- `references/volumes.md` — Persistent storage, file management, v2 volumes
- `references/secrets.md` — Credentials, environment variables, dotenv
- `references/web-endpoints.md` — FastAPI, ASGI/WSGI, streaming, auth, WebSockets
- `references/scheduled-jobs.md` — Cron, periodic schedules, management
- `references/scaling.md` — Autoscaling, concurrency, .map(), limits
- `references/resources.md` — CPU, memory, disk, timeout configuration
- `references/examples.md` — Common use cases and patterns
- `references/api_reference.md` — Key API classes and methods

Read these files when detailed information is needed beyond this overview.

{
  "format": "aiskill/v1",
  "skill": {
    "name": "modal",
    "slug": "modal",
    "version": "1.0.0",
    "description": "Cloud computing platform for running Python on GPUs and serverless infrastructure. Use when deploying AI/ML models, running GPU-accelerated workloads, serving web endpoints, scheduling batch jobs, or scaling Python code to the cloud. Use this skill whenever the user mentions Modal, serverless GPU compute, deploying ML models to the cloud, serving inference endpoints, running batch processing in the cloud, or needs to scale Python workloads beyond their local machine. Also use when the user wants to run code on H100s, A100s, or other cloud GPUs, or needs to create a web API for a model.",
    "category": "Research",
    "tags": [
      "research-science",
      "infrastructure",
      "python",
      "api"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "APACHE-2.0"
  },
  "prompts": {
    "system": "# Modal\r\n\r\n## Overview\r\n\r\nModal is a cloud platform for running Python code serverlessly, with a focus on AI/ML workloads. Key capabilities:\r\n- **GPU compute** on demand (T4, L4, A10, L40S, A100, H100, H200, B200)\r\n- **Serverless functions** with autoscaling from zero to thousands of containers\r\n- **Custom container images** built entirely in Python code\r\n- **Persistent storage** via Volumes for model weights and datasets\r\n- **Web endpoints** for serving models and APIs\r\n- **Scheduled jobs** via cron or fixed intervals\r\n- **Sub-second cold starts** for low-latency inference\r\n\r\nEverything in Modal is defined as code — no YAML, no Dockerfiles required (though both are supported).\r\n\r\n## When to Use This Skill\r\n\r\nUse this skill when:\r\n- Deploy or serve AI/ML models in the cloud\r\n- Run GPU-accelerated computations (training, inference, fine-tuning)\r\n- Create serverless web APIs or endpoints\r\n- Scale batch processing jobs in parallel\r\n- Schedule recurring tasks (data pipelines, retraining, scraping)\r\n- Need persistent cloud storage for model weights or datasets\r\n- Want to run code in custom container environments\r\n- Build job queues or async task processing systems\r\n\r\n## Installation and Authentication\r\n\r\n### Install\r\n\r\n```bash\r\nuv pip install modal\r\n```\r\n\r\n### Authenticate\r\n\r\nPrefer existing credentials before creating new ones:\r\n\r\n1. Check whether `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` are already present in the current environment.\r\n2. If not, check for those values in a local `.env` file and load them if appropriate for the workflow.\r\n3. Only fall back to interactive `modal setup` or generating fresh tokens if neither source already provides credentials.\r\n\r\n```bash\r\nmodal setup\r\n```\r\n\r\nThis opens a browser for authentication. For CI/CD or headless environments, use environment variables:\r\n\r\n```bash\r\nexport MODAL_TOKEN_ID=<your-token-id>\r\nexport MODAL_TOKEN_SECRET=<your-token-secret>\r\n```\r\n\r\nIf tokens are not already available in the environment or `.env`, generate them at https://modal.com/settings\r\n\r\nModal offers a free tier with $30/month in credits.\r\n\r\n**Reference**: See `references/getting-started.md` for detailed setup and first app walkthrough.\r\n\r\n## Core Concepts\r\n\r\n### App and Functions\r\n\r\nA Modal `App` groups related functions. Functions decorated with `@app.function()` run remotely in the cloud:\r\n\r\n```python\r\nimport modal\r\n\r\napp = modal.App(\"my-app\")\r\n\r\n@app.function()\r\ndef square(x):\r\n    return x ** 2\r\n\r\n@app.local_entrypoint()\r\ndef main():\r\n    # .remote() runs in the cloud\r\n    print(square.remote(42))\r\n```\r\n\r\nRun with `modal run script.py`. Deploy with `modal deploy script.py`.\r\n\r\n**Reference**: See `references/functions.md` for lifecycle hooks, classes, `.map()`, `.spawn()`, and more.\r\n\r\n### Container Images\r\n\r\nModal builds container images from Python code. The recommended package installer is `uv`:\r\n\r\n```python\r\nimage = (\r\n    modal.Image.debian_slim(python_version=\"3.11\")\r\n    .uv_pip_install(\"torch==2.8.0\", \"transformers\", \"accelerate\")\r\n    .apt_install(\"git\")\r\n)\r\n\r\n@app.function(image=image)\r\ndef inference(prompt):\r\n    from transformers import pipeline\r\n    pipe = pipeline(\"text-generation\", model=\"meta-llama/Llama-3-8B\")\r\n    return pipe(prompt)\r\n```\r\n\r\nKey image methods:\r\n- `.uv_pip_install()` — Install Python packages with uv (recommended)\r\n- `.pip_install()` — Install with pip (fallback)\r\n- `.apt_install()` — Install system packages\r\n- `.run_commands()` — Run shell commands during build\r\n- `.run_function()` — Run Python during build (e.g., download model weights)\r\n- `.add_local_python_source()` — Add local modules\r\n- `.env()` — Set environment variables\r\n\r\n**Reference**: See `references/images.md` for Dockerfiles, micromamba, caching, GPU build steps.\r\n\r\n### GPU Compute\r\n\r\nRequest GPUs via the `gpu` parameter:\r\n\r\n```python\r\n@app.function(gpu=\"H100\")\r\ndef train_model():\r\n    import torch\r\n    device = torch.device(\"cuda\")\r\n    # GPU training code here\r\n\r\n# Multiple GPUs\r\n@app.function(gpu=\"H100:4\")\r\ndef distributed_training():\r\n    ...\r\n\r\n# GPU fallback chain\r\n@app.function(gpu=[\"H100\", \"A100-80GB\", \"A100-40GB\"])\r\ndef flexible_inference():\r\n    ...\r\n```\r\n\r\nAvailable GPUs: T4, L4, A10, L40S, A100-40GB, A100-80GB, H100, H200, B200, B200+\r\n\r\n- Up to 8 GPUs per container (except A10: up to 4)\r\n- L40S is recommended for inference (cost/performance balance, 48 GB VRAM)\r\n- H100/A100 can be auto-upgraded to H200/A100-80GB at no extra cost\r\n- Use `gpu=\"H100!\"` to prevent auto-upgrade\r\n\r\n**Reference**: See `references/gpu.md` for GPU selection guidance and multi-GPU training.\r\n\r\n### Volumes (Persistent Storage)\r\n\r\nVolumes provide distributed, persistent file storage:\r\n\r\n```python\r\nvol = modal.Volume.from_name(\"model-weights\", create_if_missing=True)\r\n\r\n@app.function(volumes={\"/data\": vol})\r\ndef save_model():\r\n    # Write to the mounted path\r\n    with open(\"/data/model.pt\", \"wb\") as f:\r\n        torch.save(model.state_dict(), f)\r\n\r\n@app.function(volumes={\"/data\": vol})\r\ndef load_model():\r\n    model.load_state_dict(torch.load(\"/data/model.pt\"))\r\n```\r\n\r\n- Optimized for write-once, read-many workloads (model weights, datasets)\r\n- CLI access: `modal volume ls`, `modal volume put`, `modal volume get`\r\n- Background auto-commits every few seconds\r\n\r\n**Reference**: See `references/volumes.md` for v2 volumes, concurrent writes, and best practices.\r\n\r\n### Secrets\r\n\r\nSecurely pass credentials to functions:\r\n\r\n```python\r\n@app.function(secrets=[modal.Secret.from_name(\"my-api-keys\")])\r\ndef call_api():\r\n    import os\r\n    api_key = os.environ[\"API_KEY\"]\r\n    # Use the key\r\n```\r\n\r\nCreate secrets via CLI: `modal secret create my-api-keys API_KEY=sk-xxx`\r\n\r\nOr from a `.env` file: `modal.Secret.from_dotenv()`\r\n\r\n**Reference**: See `references/secrets.md` for dashboard setup, multiple secrets, and templates.\r\n\r\n### Web Endpoints\r\n\r\nServe models and APIs as web endpoints:\r\n\r\n```python\r\n@app.function()\r\n@modal.fastapi_endpoint()\r\ndef predict(text: str):\r\n    return {\"result\": model.predict(text)}\r\n```\r\n\r\n- `modal serve script.py` — Development with hot reload and temporary URL\r\n- `modal deploy script.py` — Production deployment with permanent URL\r\n- Supports FastAPI, ASGI (Starlette, FastHTML), WSGI (Flask, Django), WebSockets\r\n- Request bodies up to 4 GiB, unlimited response size\r\n\r\n**Reference**: See `references/web-endpoints.md` for ASGI/WSGI apps, streaming, auth, and WebSockets.\r\n\r\n### Scheduled Jobs\r\n\r\nRun functions on a schedule:\r\n\r\n```python\r\n@app.function(schedule=modal.Cron(\"0 9 * * *\"))  # Daily at 9 AM UTC\r\ndef daily_pipeline():\r\n    # ETL, retraining, scraping, etc.\r\n    ...\r\n\r\n@app.function(schedule=modal.Period(hours=6))\r\ndef periodic_check():\r\n    ...\r\n```\r\n\r\nDeploy with `modal deploy script.py` to activate the schedule.\r\n\r\n- `modal.Cron(\"...\")` — Standard cron syntax, stable across deploys\r\n- `modal.Period(hours=N)` — Fixed interval, resets on redeploy\r\n- Monitor runs in the Modal dashboard\r\n\r\n**Reference**: See `references/scheduled-jobs.md` for cron syntax and management.\r\n\r\n### Scaling and Concurrency\r\n\r\nModal autoscales containers automatically. Configure limits:\r\n\r\n```python\r\n@app.function(\r\n    max_containers=100,    # Upper limit\r\n    min_containers=2,      # Keep warm for low latency\r\n    buffer_containers=5,   # Reserve capacity\r\n    scaledown_window=300,  # Idle seconds before shutdown\r\n)\r\ndef process(data):\r\n    ...\r\n```\r\n\r\nProcess inputs in parallel with `.map()`:\r\n\r\n```python\r\nresults = list(process.map([item1, item2, item3, ...]))\r\n```\r\n\r\nEnable concurrent request handling per container:\r\n\r\n```python\r\n@app.function()\r\n@modal.concurrent(max_inputs=10)\r\nasync def handle_request(req):\r\n    ...\r\n```\r\n\r\n**Reference**: See `references/scaling.md` for `.map()`, `.starmap()`, `.spawn()`, and limits.\r\n\r\n### Resource Configuration\r\n\r\n```python\r\n@app.function(\r\n    cpu=4.0,              # Physical cores (not vCPUs)\r\n    memory=16384,         # MiB\r\n    ephemeral_disk=51200, # MiB (up to 3 TiB)\r\n    timeout=3600,         # Seconds\r\n)\r\ndef heavy_computation():\r\n    ...\r\n```\r\n\r\nDefaults: 0.125 CPU cores, 128 MiB memory. Billed on max(request, usage).\r\n\r\n**Reference**: See `references/resources.md` for limits and billing details.\r\n\r\n## Classes with Lifecycle Hooks\r\n\r\nFor stateful workloads (e.g., loading a model once and serving many requests):\r\n\r\n```python\r\n@app.cls(gpu=\"L40S\", image=image)\r\nclass Predictor:\r\n    @modal.enter()\r\n    def load_model(self):\r\n        self.model = load_heavy_model()  # Runs once on container start\r\n\r\n    @modal.method()\r\n    def predict(self, text: str):\r\n        return self.model(text)\r\n\r\n    @modal.exit()\r\n    def cleanup(self):\r\n        ...  # Runs on container shutdown\r\n```\r\n\r\nCall with: `Predictor().predict.remote(\"hello\")`\r\n\r\n## Common Workflow Patterns\r\n\r\n### GPU Model Inference Service\r\n\r\n```python\r\nimport modal\r\n\r\napp = modal.App(\"llm-service\")\r\n\r\nimage = (\r\n    modal.Image.debian_slim(python_version=\"3.11\")\r\n    .uv_pip_install(\"vllm\")\r\n)\r\n\r\n@app.cls(gpu=\"H100\", image=image, min_containers=1)\r\nclass LLMService:\r\n    @modal.enter()\r\n    def load(self):\r\n        from vllm import LLM\r\n        self.llm = LLM(model=\"meta-llama/Llama-3-70B\")\r\n\r\n    @modal.method()\r\n    @modal.fastapi_endpoint(method=\"POST\")\r\n    def generate(self, prompt: str, max_tokens: int = 256):\r\n        outputs = self.llm.generate([prompt], max_tokens=max_tokens)\r\n        return {\"text\": outputs[0].outputs[0].text}\r\n```\r\n\r\n### Batch Processing Pipeline\r\n\r\n```python\r\napp = modal.App(\"batch-pipeline\")\r\nvol = modal.Volume.from_name(\"pipeline-data\", create_if_missing=True)\r\n\r\n@app.function(volumes={\"/data\": vol}, cpu=4.0, memory=8192)\r\ndef process_chunk(chunk_id: int):\r\n    import pandas as pd\r\n    df = pd.read_parquet(f\"/data/input/chunk_{chunk_id}.parquet\")\r\n    result = heavy_transform(df)\r\n    result.to_parquet(f\"/data/output/chunk_{chunk_id}.parquet\")\r\n    return len(result)\r\n\r\n@app.local_entrypoint()\r\ndef main():\r\n    chunk_ids = list(range(100))\r\n    results = list(process_chunk.map(chunk_ids))\r\n    print(f\"Processed {sum(results)} total rows\")\r\n```\r\n\r\n### Scheduled Data Pipeline\r\n\r\n```python\r\napp = modal.App(\"etl-pipeline\")\r\n\r\n@app.function(\r\n    schedule=modal.Cron(\"0 */6 * * *\"),  # Every 6 hours\r\n    secrets=[modal.Secret.from_name(\"db-credentials\")],\r\n)\r\ndef etl_job():\r\n    import os\r\n    db_url = os.environ[\"DATABASE_URL\"]\r\n    # Extract, transform, load\r\n    ...\r\n```\r\n\r\n## CLI Reference\r\n\r\n| Command | Description |\r\n|---------|-------------|\r\n| `modal setup` | Authenticate with Modal |\r\n| `modal run script.py` | Run a script's local entrypoint |\r\n| `modal serve script.py` | Dev server with hot reload |\r\n| `modal deploy script.py` | Deploy to production |\r\n| `modal volume ls <name>` | List files in a volume |\r\n| `modal volume put <name> <file>` | Upload file to volume |\r\n| `modal volume get <name> <file>` | Download file from volume |\r\n| `modal secret create <name> K=V` | Create a secret |\r\n| `modal secret list` | List secrets |\r\n| `modal app list` | List deployed apps |\r\n| `modal app stop <name>` | Stop a deployed app |\r\n\r\n## Reference Files\r\n\r\nDetailed documentation for each topic:\r\n\r\n- `references/getting-started.md` — Installation, authentication, first app\r\n- `references/functions.md` — Functions, classes, lifecycle hooks, remote execution\r\n- `references/images.md` — Container images, package installation, caching\r\n- `references/gpu.md` — GPU types, selection, multi-GPU, training\r\n- `references/volumes.md` — Persistent storage, file management, v2 volumes\r\n- `references/secrets.md` — Credentials, environment variables, dotenv\r\n- `references/web-endpoints.md` — FastAPI, ASGI/WSGI, streaming, auth, WebSockets\r\n- `references/scheduled-jobs.md` — Cron, periodic schedules, management\r\n- `references/scaling.md` — Autoscaling, concurrency, .map(), limits\r\n- `references/resources.md` — CPU, memory, disk, timeout configuration\r\n- `references/examples.md` — Common use cases and patterns\r\n- `references/api_reference.md` — Key API classes and methods\r\n\r\nRead these files when detailed information is needed beyond this overview.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The modal/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/modal",
    "exported_at": "2026-11-03T07:42:39.543Z"
  }
}

format: aiskill/v1
skill:
  name: modal
  slug: modal
  version: 1.0.0
  description: >-
    Cloud computing platform for running Python on GPUs and serverless infrastructure. Use when
    deploying AI/ML models, running GPU-accelerated workloads, serving web endpoints, scheduling
    batch jobs, or scaling Python code to the cloud. Use this skill whenever the user mentions
    Modal, serverless GPU compute, deploying ML models to the cloud, serving inference endpoints,
    running batch processing in the cloud, or needs to scale Python workloads beyond their local
    machine. Also use when the user wants to run code on H100s, A100s, or other cloud GPUs, or needs
    to create a web API for a model.
  category: Research
  tags:
    - research-science
    - infrastructure
    - python
    - api
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: APACHE-2.0
prompts:
  system: "# Modal\r\n\r\n## Overview\r\n\r\nModal is a cloud platform for running Python code serverlessly, with a focus on AI/ML workloads. Key capabilities:\r\n- **GPU compute** on demand (T4, L4, A10, L40S, A100, H100, H200, B200)\r\n- **Serverless functions** with autoscaling from zero to thousands of containers\r\n- **Custom container images** built entirely in Python code\r\n- **Persistent storage** via Volumes for model weights and datasets\r\n- **Web endpoints** for serving models and APIs\r\n- **Scheduled jobs** via cron or fixed intervals\r\n- **Sub-second cold starts** for low-latency inference\r\n\r\nEverything in Modal is defined as code — no YAML, no Dockerfiles required (though both are supported).\r\n\r\n## When to Use This Skill\r\n\r\nUse this skill when:\r\n- Deploy or serve AI/ML models in the cloud\r\n- Run GPU-accelerated computations (training, inference, fine-tuning)\r\n- Create serverless web APIs or endpoints\r\n- Scale batch processing jobs in parallel\r\n- Schedule recurring tasks (data pipelines, retraining, scraping)\r\n- Need persistent cloud storage for model weights or datasets\r\n- Want to run code in custom container environments\r\n- Build job queues or async task processing systems\r\n\r\n## Installation and Authentication\r\n\r\n### Install\r\n\r\n```bash\r\nuv pip install modal\r\n```\r\n\r\n### Authenticate\r\n\r\nPrefer existing credentials before creating new ones:\r\n\r\n1. Check whether `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` are already present in the current environment.\r\n2. If not, check for those values in a local `.env` file and load them if appropriate for the workflow.\r\n3. Only fall back to interactive `modal setup` or generating fresh tokens if neither source already provides credentials.\r\n\r\n```bash\r\nmodal setup\r\n```\r\n\r\nThis opens a browser for authentication. For CI/CD or headless environments, use environment variables:\r\n\r\n```bash\r\nexport MODAL_TOKEN_ID=<your-token-id>\r\nexport MODAL_TOKEN_SECRET=<your-token-secret>\r\n```\r\n\r\nIf tokens are not already available in the environment or `.env`, generate them at https://modal.com/settings\r\n\r\nModal offers a free tier with $30/month in credits.\r\n\r\n**Reference**: See `references/getting-started.md` for detailed setup and first app walkthrough.\r\n\r\n## Core Concepts\r\n\r\n### App and Functions\r\n\r\nA Modal `App` groups related functions. Functions decorated with `@app.function()` run remotely in the cloud:\r\n\r\n```python\r\nimport modal\r\n\r\napp = modal.App(\"my-app\")\r\n\r\n@app.function()\r\ndef square(x):\r\n    return x ** 2\r\n\r\n@app.local_entrypoint()\r\ndef main():\r\n    # .remote() runs in the cloud\r\n    print(square.remote(42))\r\n```\r\n\r\nRun with `modal run script.py`. Deploy with `modal deploy script.py`.\r\n\r\n**Reference**: See `references/functions.md` for lifecycle hooks, classes, `.map()`, `.spawn()`, and more.\r\n\r\n### Container Images\r\n\r\nModal builds container images from Python code. The recommended package installer is `uv`:\r\n\r\n```python\r\nimage = (\r\n    modal.Image.debian_slim(python_version=\"3.11\")\r\n    .uv_pip_install(\"torch==2.8.0\", \"transformers\", \"accelerate\")\r\n    .apt_install(\"git\")\r\n)\r\n\r\n@app.function(image=image)\r\ndef inference(prompt):\r\n    from transformers import pipeline\r\n    pipe = pipeline(\"text-generation\", model=\"meta-llama/Llama-3-8B\")\r\n    return pipe(prompt)\r\n```\r\n\r\nKey image methods:\r\n- `.uv_pip_install()` — Install Python packages with uv (recommended)\r\n- `.pip_install()` — Install with pip (fallback)\r\n- `.apt_install()` — Install system packages\r\n- `.run_commands()` — Run shell commands during build\r\n- `.run_function()` — Run Python during build (e.g., download model weights)\r\n- `.add_local_python_source()` — Add local modules\r\n- `.env()` — Set environment variables\r\n\r\n**Reference**: See `references/images.md` for Dockerfiles, micromamba, caching, GPU build steps.\r\n\r\n### GPU Compute\r\n\r\nRequest GPUs via the `gpu` parameter:\r\n\r\n```python\r\n@app.function(gpu=\"H100\")\r\ndef train_model():\r\n    import torch\r\n    device = torch.device(\"cuda\")\r\n    # GPU training code here\r\n\r\n# Multiple GPUs\r\n@app.function(gpu=\"H100:4\")\r\ndef distributed_training():\r\n    ...\r\n\r\n# GPU fallback chain\r\n@app.function(gpu=[\"H100\", \"A100-80GB\", \"A100-40GB\"])\r\ndef flexible_inference():\r\n    ...\r\n```\r\n\r\nAvailable GPUs: T4, L4, A10, L40S, A100-40GB, A100-80GB, H100, H200, B200, B200+\r\n\r\n- Up to 8 GPUs per container (except A10: up to 4)\r\n- L40S is recommended for inference (cost/performance balance, 48 GB VRAM)\r\n- H100/A100 can be auto-upgraded to H200/A100-80GB at no extra cost\r\n- Use `gpu=\"H100!\"` to prevent auto-upgrade\r\n\r\n**Reference**: See `references/gpu.md` for GPU selection guidance and multi-GPU training.\r\n\r\n### Volumes (Persistent Storage)\r\n\r\nVolumes provide distributed, persistent file storage:\r\n\r\n```python\r\nvol = modal.Volume.from_name(\"model-weights\", create_if_missing=True)\r\n\r\n@app.function(volumes={\"/data\": vol})\r\ndef save_model():\r\n    # Write to the mounted path\r\n    with open(\"/data/model.pt\", \"wb\") as f:\r\n        torch.save(model.state_dict(), f)\r\n\r\n@app.function(volumes={\"/data\": vol})\r\ndef load_model():\r\n    model.load_state_dict(torch.load(\"/data/model.pt\"))\r\n```\r\n\r\n- Optimized for write-once, read-many workloads (model weights, datasets)\r\n- CLI access: `modal volume ls`, `modal volume put`, `modal volume get`\r\n- Background auto-commits every few seconds\r\n\r\n**Reference**: See `references/volumes.md` for v2 volumes, concurrent writes, and best practices.\r\n\r\n### Secrets\r\n\r\nSecurely pass credentials to functions:\r\n\r\n```python\r\n@app.function(secrets=[modal.Secret.from_name(\"my-api-keys\")])\r\ndef call_api():\r\n    import os\r\n    api_key = os.environ[\"API_KEY\"]\r\n    # Use the key\r\n```\r\n\r\nCreate secrets via CLI: `modal secret create my-api-keys API_KEY=sk-xxx`\r\n\r\nOr from a `.env` file: `modal.Secret.from_dotenv()`\r\n\r\n**Reference**: See `references/secrets.md` for dashboard setup, multiple secrets, and templates.\r\n\r\n### Web Endpoints\r\n\r\nServe models and APIs as web endpoints:\r\n\r\n```python\r\n@app.function()\r\n@modal.fastapi_endpoint()\r\ndef predict(text: str):\r\n    return {\"result\": model.predict(text)}\r\n```\r\n\r\n- `modal serve script.py` — Development with hot reload and temporary URL\r\n- `modal deploy script.py` — Production deployment with permanent URL\r\n- Supports FastAPI, ASGI (Starlette, FastHTML), WSGI (Flask, Django), WebSockets\r\n- Request bodies up to 4 GiB, unlimited response size\r\n\r\n**Reference**: See `references/web-endpoints.md` for ASGI/WSGI apps, streaming, auth, and WebSockets.\r\n\r\n### Scheduled Jobs\r\n\r\nRun functions on a schedule:\r\n\r\n```python\r\n@app.function(schedule=modal.Cron(\"0 9 * * *\"))  # Daily at 9 AM UTC\r\ndef daily_pipeline():\r\n    # ETL, retraining, scraping, etc.\r\n    ...\r\n\r\n@app.function(schedule=modal.Period(hours=6))\r\ndef periodic_check():\r\n    ...\r\n```\r\n\r\nDeploy with `modal deploy script.py` to activate the schedule.\r\n\r\n- `modal.Cron(\"...\")` — Standard cron syntax, stable across deploys\r\n- `modal.Period(hours=N)` — Fixed interval, resets on redeploy\r\n- Monitor runs in the Modal dashboard\r\n\r\n**Reference**: See `references/scheduled-jobs.md` for cron syntax and management.\r\n\r\n### Scaling and Concurrency\r\n\r\nModal autoscales containers automatically. Configure limits:\r\n\r\n```python\r\n@app.function(\r\n    max_containers=100,    # Upper limit\r\n    min_containers=2,      # Keep warm for low latency\r\n    buffer_containers=5,   # Reserve capacity\r\n    scaledown_window=300,  # Idle seconds before shutdown\r\n)\r\ndef process(data):\r\n    ...\r\n```\r\n\r\nProcess inputs in parallel with `.map()`:\r\n\r\n```python\r\nresults = list(process.map([item1, item2, item3, ...]))\r\n```\r\n\r\nEnable concurrent request handling per container:\r\n\r\n```python\r\n@app.function()\r\n@modal.concurrent(max_inputs=10)\r\nasync def handle_request(req):\r\n    ...\r\n```\r\n\r\n**Reference**: See `references/scaling.md` for `.map()`, `.starmap()`, `.spawn()`, and limits.\r\n\r\n### Resource Configuration\r\n\r\n```python\r\n@app.function(\r\n    cpu=4.0,              # Physical cores (not vCPUs)\r\n    memory=16384,         # MiB\r\n    ephemeral_disk=51200, # MiB (up to 3 TiB)\r\n    timeout=3600,         # Seconds\r\n)\r\ndef heavy_computation():\r\n    ...\r\n```\r\n\r\nDefaults: 0.125 CPU cores, 128 MiB memory. Billed on max(request, usage).\r\n\r\n**Reference**: See `references/resources.md` for limits and billing details.\r\n\r\n## Classes with Lifecycle Hooks\r\n\r\nFor stateful workloads (e.g., loading a model once and serving many requests):\r\n\r\n```python\r\n@app.cls(gpu=\"L40S\", image=image)\r\nclass Predictor:\r\n    @modal.enter()\r\n    def load_model(self):\r\n        self.model = load_heavy_model()  # Runs once on container start\r\n\r\n    @modal.method()\r\n    def predict(self, text: str):\r\n        return self.model(text)\r\n\r\n    @modal.exit()\r\n    def cleanup(self):\r\n        ...  # Runs on container shutdown\r\n```\r\n\r\nCall with: `Predictor().predict.remote(\"hello\")`\r\n\r\n## Common Workflow Patterns\r\n\r\n### GPU Model Inference Service\r\n\r\n```python\r\nimport modal\r\n\r\napp = modal.App(\"llm-service\")\r\n\r\nimage = (\r\n    modal.Image.debian_slim(python_version=\"3.11\")\r\n    .uv_pip_install(\"vllm\")\r\n)\r\n\r\n@app.cls(gpu=\"H100\", image=image, min_containers=1)\r\nclass LLMService:\r\n    @modal.enter()\r\n    def load(self):\r\n        from vllm import LLM\r\n        self.llm = LLM(model=\"meta-llama/Llama-3-70B\")\r\n\r\n    @modal.method()\r\n    @modal.fastapi_endpoint(method=\"POST\")\r\n    def generate(self, prompt: str, max_tokens: int = 256):\r\n        outputs = self.llm.generate([prompt], max_tokens=max_tokens)\r\n        return {\"text\": outputs[0].outputs[0].text}\r\n```\r\n\r\n### Batch Processing Pipeline\r\n\r\n```python\r\napp = modal.App(\"batch-pipeline\")\r\nvol = modal.Volume.from_name(\"pipeline-data\", create_if_missing=True)\r\n\r\n@app.function(volumes={\"/data\": vol}, cpu=4.0, memory=8192)\r\ndef process_chunk(chunk_id: int):\r\n    import pandas as pd\r\n    df = pd.read_parquet(f\"/data/input/chunk_{chunk_id}.parquet\")\r\n    result = heavy_transform(df)\r\n    result.to_parquet(f\"/data/output/chunk_{chunk_id}.parquet\")\r\n    return len(result)\r\n\r\n@app.local_entrypoint()\r\ndef main():\r\n    chunk_ids = list(range(100))\r\n    results = list(process_chunk.map(chunk_ids))\r\n    print(f\"Processed {sum(results)} total rows\")\r\n```\r\n\r\n### Scheduled Data Pipeline\r\n\r\n```python\r\napp = modal.App(\"etl-pipeline\")\r\n\r\n@app.function(\r\n    schedule=modal.Cron(\"0 */6 * * *\"),  # Every 6 hours\r\n    secrets=[modal.Secret.from_name(\"db-credentials\")],\r\n)\r\ndef etl_job():\r\n    import os\r\n    db_url = os.environ[\"DATABASE_URL\"]\r\n    # Extract, transform, load\r\n    ...\r\n```\r\n\r\n## CLI Reference\r\n\r\n| Command | Description |\r\n|---------|-------------|\r\n| `modal setup` | Authenticate with Modal |\r\n| `modal run script.py` | Run a script's local entrypoint |\r\n| `modal serve script.py` | Dev server with hot reload |\r\n| `modal deploy script.py` | Deploy to production |\r\n| `modal volume ls <name>` | List files in a volume |\r\n| `modal volume put <name> <file>` | Upload file to volume |\r\n| `modal volume get <name> <file>` | Download file from volume |\r\n| `modal secret create <name> K=V` | Create a secret |\r\n| `modal secret list` | List secrets |\r\n| `modal app list` | List deployed apps |\r\n| `modal app stop <name>` | Stop a deployed app |\r\n\r\n## Reference Files\r\n\r\nDetailed documentation for each topic:\r\n\r\n- `references/getting-started.md` — Installation, authentication, first app\r\n- `references/functions.md` — Functions, classes, lifecycle hooks, remote execution\r\n- `references/images.md` — Container images, package installation, caching\r\n- `references/gpu.md` — GPU types, selection, multi-GPU, training\r\n- `references/volumes.md` — Persistent storage, file management, v2 volumes\r\n- `references/secrets.md` — Credentials, environment variables, dotenv\r\n- `references/web-endpoints.md` — FastAPI, ASGI/WSGI, streaming, auth, WebSockets\r\n- `references/scheduled-jobs.md` — Cron, periodic schedules, management\r\n- `references/scaling.md` — Autoscaling, concurrency, .map(), limits\r\n- `references/resources.md` — CPU, memory, disk, timeout configuration\r\n- `references/examples.md` — Common use cases and patterns\r\n- `references/api_reference.md` — Key API classes and methods\r\n\r\nRead these files when detailed information is needed beyond this overview."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The modal/ folder contains SKILL.md
        plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/modal
  exported_at: "2026-11-03T07:42:39.543Z"