# ComfyUI Model Directory Layout (CT 204 Reference)

Canonical path inside the LXC: `/opt/ComfyUI/models/`

## Directory-to-Node Mapping

| Directory | ComfyUI Node Type | Example Models |
|---|---|---|
| `checkpoints/` | Load Checkpoint | legacy `.ckpt`, `.safetensors` |
| `diffusion_models/` | Load Diffusion Model | Flux, SD3, Ideogram, etc. |
| `text_encoders/` | CLIP Text Encode | T5, Qwen-VL, CLIP-L, etc. |
| `vae/` | Load VAE | SD VAE, Flux VAE |
| `unet/` | deprecated alias for diffusion_models | — |
| `clip/` | Load CLIP | CLIP models (some workflows use this instead of text_encoders) |
| `clip_vision/` | CLIP Vision Encode | image-to-text encoders |
| `controlnet/` | Load ControlNet | `.safetensors` control nets |
| `loras/` | Load LoRA | `.safetensors` LoRAs |
| `embeddings/` | Embedding | textual inversion files |
| `upscale_models/` | Upscale Model | ESRGAN, RealESRGAN |
| `vae_approx/` | VAE Decode (taesd) | TAESD approx decoder |

## Model Source URLs

### HuggingFace

Always use `resolve` URL + `-O` filename:

```bash
cd /opt/ComfyUI/models/diffusion_models
wget -c "https://huggingface.co/Comfy-Org/Ideogram-4/resolve/main/diffusion_models/ideogram4_fp8_scaled.safetensors" -O ideogram4_fp8_scaled.safetensors
```

- `blob` URL → HTML preview page (wrong)
- `resolve` URL → 302 to CDN, then binary (correct)
- `-O` ensures predictable filename regardless of redirect

### CivitAI

CivitAI model page is NOT the download URL:

```bash
# WRONG - downloads HTML page
wget "https://civitai.com/models/12345/model-name"

# CORRECT - api download endpoint
wget "https://civitai.com/api/download/models/67890?type=Model&format=SafeTensor" -O model.safetensors
```

## Verifying Downloads

```bash
ls -lh /opt/ComfyUI/models/diffusion_models/
file /opt/ComfyUI/models/diffusion_models/*.safetensors
```

`file` should report `data` or similar binary type, not `HTML document`.

## Parallel Downloads

When queueing multiple large models, run each in background and poll:

```bash
# Start 3 downloads in parallel
pct exec 204 -- bash -c 'cd /opt/ComfyUI/models/text_encoders && nohup wget -c --tries=0 --read-timeout=30 "..." -O qwen3vl_8b_fp8_scaled.safetensors > /tmp/qwen_dl.log 2>&1 &'
pct exec 204 -- bash -c 'cd /opt/ComfyUI/models/diffusion_models && nohup wget -c --tries=0 --read-timeout=30 "..." -O ideogram4_fp8_scaled.safetensors > /tmp/ideogram_dl.log 2>&1 &'

# Poll
pct exec 204 -- tail -5 /tmp/qwen_dl.log
pct exec 204 -- ls -lh /opt/ComfyUI/models/
```

## Disk Space Planning

| Model Type | Typical Size | Notes |
|---|---|---|
| FLUX/SD XL diffusion model | 7–17 GB | FP8/FP16 |
| Text encoder (T5-XXL) | 10 GB | often largest single file |
| VAE | 300–800 MB | small |
| LoRA | 50–500 MB | small, many files |
| Checkpoint (.ckpt) | 4–7 GB | deprecated for Flux |

Total for a single workflow: 20–35 GB minimum. Plan LXC rootfs accordingly.