# Add a Model

This guide walks you through adding a new model (checkpoint, LoRA, VAE, etc.) to the deployment.

## Overview

Models are defined in `server/comfy.py` in the `MODELS` dict. Each entry is:
```python
["filename_on_server.safetensors", "https://direct-download-url"]
```

After editing, you deploy with `make deploy` — models are downloaded on the first workflow run and cached forever on fal's persistent storage.

## Step 1 — Find the HuggingFace URL

For a HuggingFace model page like `huggingface.co/Lightricks/LTX-2.3`, find the file you want and get its direct download URL:

```
https://huggingface.co/<ORG>/<REPO>/resolve/main/<FILE_PATH>
```

**Example:**
- File: `ltx-2.3-22b-dev.safetensors` in `Lightricks/LTX-2.3`
- URL: `https://huggingface.co/Lightricks/LTX-2.3/resolve/main/ltx-2.3-22b-dev.safetensors`

## Step 2 — Identify the right folder

This is critical. ComfyUI looks for models in specific folders based on the loader node used.

| Model type | Folder | Loader node |
|------------|--------|-------------|
| SDXL / SD / LTX 2.3 checkpoints | `checkpoints` | CheckpointLoaderSimple |
| FLUX / WAN / Qwen diffusion transformers | `diffusion_models` | UNETLoader |
| LoRAs | `loras` | LoraLoader |
| VAEs | `vae` | VAELoader |
| CLIP / text encoders | `clip` | CLIPLoader |
| Upscale models (RealESRGAN, etc.) | `upscale_models` | UpscaleModelLoader |
| Latent upscalers (LTX spatial/temporal) | `latent_upscale_models` | — |
| ControlNet | `controlnet` | ControlNetLoader |
| Style models | `style_models` | StyleModelLoader |
| Embeddings | `embeddings` | — |

> **When in doubt:** check the model's HuggingFace README or official docs for the folder placement.

## Step 3 — Add it to `server/comfy.py`

Open `server/comfy.py` and find the `MODELS` dict. Add your line in the correct folder section.

**Example** — adding a LoRA:

```python
MODELS = {
    # ...
    "loras": [
        # existing loras...
        ["my-new-lora.safetensors",
         "https://huggingface.co/user/repo/resolve/main/my-new-lora.safetensors"],
    ],
    # ...
}
```

## Step 4 — Deploy

```bash
cd server
make deploy
```

This pushes the new config. Existing runners keep the old code until they die or are killed.

## Step 5 — Kill running runners (optional, to force reload)

If you want the new model available immediately:

1. Go to https://fal.ai/dashboard/apps/<org>/<app>/runners
2. Click each active runner → **Terminate**
3. Next time someone runs a workflow, a new runner starts with the new model

On first use, the runner downloads the model from HuggingFace (can take minutes for big models). It's cached forever after.

## Troubleshooting

- **Workflow crashes with "model not found"**: wrong folder. Check Step 2.
- **Workflow crashes with "size mismatch"**: model architecture doesn't match the ComfyUI version. You may need a different variant (fp8 vs bf16 vs gguf).
- **Download fails**: check the URL is correct and public (no authentication needed).
- **Model file corrupted**: delete the cached file to force re-download:
  - Add to `server/server.py` setup: `shutil.rmtree(Path(f"/data/.fal/model_weights/{sha256_of_url}"))`
  - Deploy, wait for re-download, remove the cleanup code, redeploy

## Quick check

Models currently available:

```bash
curl -s --compressed http://localhost:8188/api/experiment/models/<folder>
# e.g. curl -s --compressed http://localhost:8188/api/experiment/models/checkpoints
```
