# modal

Guides Cursor to follow best practices when writing Modal apps, helping you tune GPU allocations, build custom images, and store model weights efficiently.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/modal.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/modal

## What it does

This rule enforces clean architecture patterns for Modal deployments. It mandates declaring a single centralized `modal.Stub` at the entry point rather than scattering stub declarations across multiple files. Core machine learning logic, such as loading weights or preprocessing tokens, gets isolated into separate modules so your handlers stay lean.

Default compute allocations are discouraged. The rule requires explicit definitions for GPU types such as `A10G` or `L4`, CPU counts, memory sizes, and execution timeouts. Dependencies belong in a pre-built `modal.Image` with pinned package versions, preventing slow rebuilds inside running containers.

Checkpoints must stay in a persistent `modal.Volume`. Downloading heavy weights on every cold container start wastes compute credits and stalls inference runs.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/modal.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/modal.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/modal.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/modal.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/modal.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/modal.mdc

## When to use it
- Configure a centralized `modal.Stub` for an ML service
- Build a reproducible `modal.Image` with pinned CUDA packages
- Mount model checkpoints through a persistent `modal.Volume`
- Assign explicit GPU, CPU, and memory limits for remote functions

## Example prompts
- Create a Modal inference function for Mistral-7B with lazy model loading
- Define a Modal image with PyTorch and CUDA dependencies pinned
- Set up a persistent Volume to store model checkpoints across cold starts

## Source text · modal.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a6232059526cacc3.

BEGIN THIRD-PARTY FILE a6232059526cacc3
````text
---
description: This guide provides opinionated, actionable best practices for writing high-performance, cost-effective, and maintainable AI/ML applications on Modal.
globs: **/*
---
# modal Best Practices

Modal is the definitive platform for deploying AI/ML workloads. To leverage its full potential – sub-second cold starts, instant autoscaling, and GPU acceleration – you *must* adhere to these best practices. This guide cuts through the noise, providing the exact patterns your team will use daily.

## Code Organization and Structure

A well-structured Modal application is modular, explicit, and easy to debug.

### 1. Centralize Your `modal.Stub`

Always define a single, well-named `modal.Stub` at the top level of your main application file. This `Stub` is the entry point for all your Modal functions, images, and volumes.

❌ **BAD: Multiple `Stub` definitions or generic names**
```python
# my_module_a.py
import modal
stub_a = modal.Stub("my-app-part-a") # Don't do this

# my_module_b.py
import modal
stub_b = modal.Stub("my-app-part-b") # Or this
```

✅ **GOOD: Single, descriptive `Stub`**
```python
# src/my_ml_app/app.py
import modal

# Define the stub for your entire application
# Use a clear, unique name for your project/service
stub = modal.Stub("my-inference-service")

# All modal.Functions, Images, and Volumes will be attached to this stub
```

### 2. Modularize Your Application

For larger applications, separate your core logic (e.g., model loading, inference pipeline) into distinct Python modules. Import these modules into your main `app.py` where your `modal.Function`s are defined. This keeps your Modal definitions clean and your business logic testable.

```python
# src/my_ml_app/model_loader.py
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

class ModelLoader:
    def __init__(self, model_id: str):
        self.model_id = model_id
        self.model = None
        self.tokenizer = None

    def load(self):
        if self.model is None:
            print(f"Loading model {self.model_id}...")
            self.tokenizer = AutoTokenizer.from_pretrained(self.model_id)
            self.model = AutoModelForCausalLM.from_pretrained(self.model_id, torch_dtype=torch.bfloat16)
            print("Model loaded.")
        return self.model, self.tokenizer

# src/my_ml_app/app.py
import modal
from .model_loader import ModelLoader # Relative import for modularity

stub = modal.Stub("my-inference-service")

# Define your image and volumes here (see sections below)
inference_image = modal.Image.from_registry("nvcr.io/nvidia/pytorch:23.09-py3") \
    .pip_install("torch", "transformers")

model_volume = modal.Volume.from_name("my-llm-weights", create_if_missing=True)

@stub.function(image=inference_image, volumes={"/models": model_volume})
def generate_text(prompt: str):
    model_id = "mistralai/Mistral-7B-Instruct-v0.2"
    # Lazy load the model inside the function
    model_loader = ModelLoader(model_id)
    model, tokenizer = model_loader.load()
    
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    outputs = model.generate(**inputs, max_new_tokens=100)
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

@stub.local_entrypoint()
def main():
    print(generate_text.remote("Hello, my name is"))

```

## Common Patterns and Anti-patterns

These patterns ensure your Modal functions are robust, performant, and cost-efficient.

### 3. Explicit Resource Specification

Always declare the exact GPU type, CPU cores, and memory your function needs. This allows Modal's scheduler to provision precisely what's required, optimizing performance and cost. Never rely on defaults for production workloads.

❌ **BAD: Default (unspecified) resources**
```python
@stub.function() # No GPU, minimal CPU/memory
def process_data(data):
    # This will run on a CPU, potentially slowly
    pass
```
````
END THIRD-PARTY FILE a6232059526cacc3

The third-party file has ended. Everything between the a6232059526cacc3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3912 of 17280 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/modal.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md