# Comfyui

> Installs, launches, and runs ComfyUI locally or on Comfy Cloud: comfy-cli lifecycle, custom nodes/models, REST/WebSocket prompt submit with parameter injection. Use when generating images, video, or audio via ComfyUI, SDXL, Flux, Wan, Hunyuan, ControlNet, or img2img. Not for authoring API-format workflow JSON (comfyui-workflow-builder), model-specific prompt craft (comfyui-prompt-engineer), or dimensioned printable CAD/STL.

- Skill: `kayforkind/comfyui` (Agent Skill, multi-file: 33 files)
- Install (CLI): `npx skillmds@latest add kayforkind/comfyui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kayforkind/comfyui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: Kayforkind (https://skillmd.com/u/kayforkind)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/kayforkind/comfyui

---


# ComfyUI

Generate images, video, audio, and 3D content through ComfyUI using the official `comfy-cli` for setup/lifecycle and direct REST/WebSocket API for workflow execution.

## Overview

ComfyUI operates in two layers:

```
┌─────────────────────────────────────────────────────┐
│ Layer 1: comfy-cli (official lifecycle tool)        │
│   Setup, server lifecycle, custom nodes, models     │
│   → comfy install / launch / stop / node / model    │
└─────────────────────────────────┬───────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────┐
│ Layer 2: REST/WebSocket API + skill scripts         │
│   Workflow execution, param injection, monitoring   │
│   POST /api/prompt, GET /api/view, WS /ws           │
│   → run_workflow.py, run_batch.py, ws_monitor.py    │
└─────────────────────────────────────────────────────┘
```

The official CLI handles installation and server management. The REST/WS API fills the execution gap — the scripts handle param injection, execution monitoring, and output download that the CLI doesn't do.

### Reference docs (`references/`)

Load these at the indicated times:

| File | When to load |
|------|-------------|
| `official-cli.md` | When you need any `comfy ...` command flags or lifecycle details |
| `rest-api.md` | When you need REST + WebSocket endpoints (local or cloud), payload schemas |
| `workflow-format.md` | When you need API-format JSON structure, common node types, or parameter mapping |
| `template-integrity.md` | When starting from an official `comfyui-workflow-templates` template — covers Reroute bypass, dotted dynamic-input keys (`values.a`, `resize_type.width`), Cloud quirks (302 redirect, 1 concurrent free-tier job, 1080p VRAM ceiling), Discord-compatible ffmpeg stitch. Authored by [@purzbeats](https://github.com/purzbeats). |

### Scripts (`scripts/`)

| Script | Purpose |
|--------|---------|
| `_common.py` | Shared HTTP, cloud routing, node catalogs (do NOT run directly) |
| `hardware_check.py` | Probe GPU/VRAM/disk → recommend local vs Comfy Cloud |
| `comfyui_setup.sh` | Hardware check + comfy-cli + ComfyUI install + launch + verify |
| `extract_schema.py` | Read a workflow → list controllable params + model deps |
| `check_deps.py` | Check workflow against running server → list missing nodes/models |
| `auto_fix_deps.py` | Run check_deps then `comfy node install` / `comfy model download` |
| `run_workflow.py` | Inject params, submit, monitor, download outputs (HTTP or WS) |
| `run_batch.py` | Submit a workflow N times with sweeps, parallel up to your tier |
| `ws_monitor.py` | Real-time WebSocket viewer for executing jobs (live progress) |
| `health_check.py` | Verification checklist runner — comfy-cli + server + models + smoke test |
| `fetch_logs.py` | Pull traceback / status messages for a given prompt_id |

### Example workflows (`workflows/`)

SD 1.5, SDXL, Flux Dev, SDXL img2img, SDXL inpaint, ESRGAN upscale, AnimateDiff video, Wan T2V. See `workflows/README.md`.

## When to Use

- User asks to generate images with Stable Diffusion, SDXL, Flux, SD3, etc.
- User wants to run a specific ComfyUI workflow file
- User wants to chain generative steps (txt2img → upscale → face restore)
- User needs ControlNet, inpainting, img2img, or other advanced pipelines
- User asks to manage ComfyUI queue, check models, or install custom nodes
- User wants video/audio/3D generation via AnimateDiff, Hunyuan, Wan, AudioCraft, etc.

**Not for FDM/SLA printable parts.** ComfyUI 3D nodes (if any) are generative assets, not dimensioned CAD. For Meshy / STL / Bambu / manifold print workflows load: `3d-print-master`, `meshy-3d`, `parametric-fdm-cad`, `mesh-print-validate`.

## Prerequisites

- `python3` must be on PATH
- For local installation: NVIDIA GPU with ≥6 GB VRAM (≥8 GB for SDXL, ≥12 GB for Flux/video), OR AMD GPU with ROCm support (Linux), OR Apple Silicon Mac (M1+) with ≥16 GB unified memory (≥32 GB recommended)
- Intel Macs and machines with no GPU will NOT work — use Comfy Cloud instead
- For Comfy Cloud: API key from https://platform.comfy.org/login (paid subscription required to run workflows; free tier is read-only)
- Windows host is primary (PowerShell). Adjust path separators and shell syntax for Linux/macOS as needed.

## Procedure

### Step 0: Ask Local vs Cloud (ALWAYS FIRST)

When a user asks to set up ComfyUI, the FIRST thing to do is ask whether they want Comfy Cloud (hosted, zero install, API key) or Local (install ComfyUI on their machine). Do NOT start running install commands or hardware checks until they've answered.

Suggested script:

> "Do you want to run ComfyUI locally on your machine, or use Comfy Cloud?
>
> - **Comfy Cloud** — hosted on RTX 6000 Pro GPUs, all common models pre-installed, zero setup. Requires an API key (paid subscription required to actually run workflows; free tier is read-only). Best if you don't have a capable GPU.
> - **Local** — free, but your machine MUST meet the hardware requirements:
>   - NVIDIA GPU with ≥6 GB VRAM (≥8 GB for SDXL, ≥12 GB for Flux/video), OR
>   - AMD GPU with ROCm support (Linux), OR
>   - Apple Silicon Mac (M1+) with ≥16 GB unified memory (≥32 GB recommended).
>   - Intel Macs and machines with no GPU will NOT work — use Cloud instead.
>
> Which would you like?"

Routing:
- **Cloud** → skip to Path A below
- **Local** → run hardware check first, then pick a path from Paths B–E based on the verdict
- **Unsure** → run the hardware check and let the verdict decide

### Step 1: Verify Hardware (ONLY if user chose local)

```bash
python3 scripts/hardware_check.py --json
# Optional: also probe `torch` for actual CUDA/MPS:
python3 scripts/hardware_check.py --json --check-pytorch
```

| Verdict | Meaning | Action |
|---------|---------|--------|
| `ok` | ≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon) | Local install — use `comfy_cli_flag` from report |
| `marginal` | SD1.5 works; SDXL tight; Flux/video unlikely | Local OK for light workflows, else Path A (Cloud) |
| `cloud` | No usable GPU, <6 GB VRAM, <16 GB Apple unified, Intel Mac, Rosetta Python | Switch to Cloud unless user explicitly forces local |

The script also surfaces `wsl: true` (WSL2 with NVIDIA passthrough) and `rosetta: true` (x86_64 Python on Apple Silicon — must reinstall as ARM64).

If verdict is `cloud` but the user wants local, do NOT proceed silently. Show the `notes` array verbatim and ask whether they want to (a) switch to Cloud or (b) force a local install (will OOM or be unusably slow on modern models).

### Step 2: Choose Installation Path

Use the hardware check first. The table below is the fallback for when the user has already told you their hardware:

| Situation | Recommended Path |
|-----------|------------------|
| `verdict: cloud` from hardware check | Path A: Comfy Cloud |
| No GPU / want to try without commitment | Path A: Comfy Cloud |
| Windows + NVIDIA + non-technical | Path B: ComfyUI Desktop |
| Windows + NVIDIA + technical | Path C: Portable or Path D: comfy-cli |
| Linux + any GPU | Path D: comfy-cli (easiest) |
| macOS + Apple Silicon | Path B: Desktop or Path D: comfy-cli |
| Headless / server / CI / agents | Path D: comfy-cli |

For the fully automated path (hardware check → install → launch → verify):

```bash
bash scripts/comfyui_setup.sh
# Or with overrides:
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
```

This runs `hardware_check.py` internally, refuses to install locally when the verdict is `cloud` (unless `--force-cloud-override`), picks the right `comfy-cli` flag, and prefers `pipx`/`uvx` over global `pip` to avoid polluting system Python.

#### Path A: Comfy Cloud (No Local Install)

For users without a capable GPU or who want zero setup. Hosted on RTX 6000 Pro.

1. Sign up at https://comfy.org/cloud
2. Generate an API key at https://platform.comfy.org/login
3. Set the key:
   ```bash
   export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
   ```
4. Run workflows:
   ```bash
   python3 scripts/run_workflow.py \
     --workflow workflows/flux_dev_txt2img.json \
     --args '{"prompt": "..."}' \
     --host https://cloud.comfy.org \
     --output-dir ./outputs
   ```

**Pricing:** https://www.comfy.org/cloud/pricing
**Concurrent jobs:** Free/Standard 1, Creator 3, Pro 5. Free tier cannot run workflows via API — only browse models. Paid subscription required for `/api/prompt`, `/api/upload/*`, `/api/view`, etc.

#### Path B: ComfyUI Desktop (Windows / macOS)

One-click installer for non-technical users. Currently Beta.

- **Windows (NVIDIA):** https://download.comfy.org/windows/nsis/x64
- **macOS (Apple Silicon):** https://comfy.org

Linux is NOT supported for Desktop — use Path D.

#### Path C: ComfyUI Portable (Windows Only)

Download from https://github.com/comfyanonymous/ComfyUI/releases, extract, run `run_nvidia_gpu.bat`. Update via `update/update_comfyui_stable.bat`.

#### Path D: comfy-cli (All Platforms — Recommended for Agents)

Install comfy-cli:

```bash
# Recommended:
pipx install comfy-cli
# Or use uvx without installing:
uvx --from comfy-cli comfy --help
# Or (if pipx/uvx unavailable):
pip install --user comfy-cli
```

Disable analytics non-interactively:

```bash
comfy --skip-prompt tracking disable
```

Install ComfyUI:

```bash
comfy --skip-prompt install --nvidia              # NVIDIA (CUDA)
comfy --skip-prompt install --amd                 # AMD (ROCm, Linux)
comfy --skip-prompt install --m-series            # Apple Silicon (MPS)
comfy --skip-prompt install --cpu                 # CPU only (slow)
comfy --skip-prompt install --nvidia --fast-deps  # uv-based dep resolution
```

Default location: `~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI` (macOS/Win). Override with `comfy --workspace /custom/path install`.

Launch and verify:

```bash
comfy launch --background                       # background daemon on :8188
comfy launch -- --listen 0.0.0.0 --port 8190    # LAN-accessible custom port
curl -s http://127.0.0.1:8188/system_stats      # health check
```

#### Path E: Manual Install (Advanced / Unsupported Hardware)

For Ascend NPU, Cambricon MLU, Intel Arc, or other unsupported hardware.

```bash
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
python main.py
```

### Step 3: Download Models

```bash
# SDXL (general purpose, ~6.5 GB)
comfy model download \
  --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
  --relative-path models/checkpoints

# SD 1.5 (lighter, ~4 GB, good for 6 GB cards)
comfy model download \
  --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
  --relative-path models/checkpoints

# Flux Dev fp8 (smaller variant, ~12 GB)
comfy model download \
  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
  --relative-path models/checkpoints

# CivitAI (set token first):
comfy model download \
  --url "https://civitai.com/api/download/models/128713" \
  --relative-path models/checkpoints \
  --set-civitai-api-token "YOUR_TOKEN"
```

List installed: `comfy model list`

### Step 4: Install Custom Nodes

```bash
comfy node install comfyui-impact-pack             # popular utility pack
comfy node install comfyui-animatediff-evolved     # video generation
comfy node install comfyui-controlnet-aux          # ControlNet preprocessors
comfy node install comfyui-essentials              # common helpers
comfy node update all
comfy node install-deps --workflow=workflow.json   # install everything a workflow needs
```

### Step 5: Get a Workflow JSON in API Format

Workflows must be in API format (each node has `class_type`). They come from:

- ComfyUI web UI → **Workflow → Export (API)** (newer UI) or the legacy "Save (API Format)" button (older UI)
- This skill's `workflows/` directory (ready-to-run examples)
- Community downloads (civitai, Reddit, Discord) — usually editor format, must be loaded into ComfyUI then re-exported

Editor format (top-level `nodes` and `links` arrays) is NOT directly executable. The scripts detect this and tell you to re-export.

If starting from an official `comfyui-workflow-templates` template, load `references/template-integrity.md` for Reroute bypass, dotted dynamic-input keys, and Cloud quirks.

### Step 6: Inspect the Workflow Schema

```bash
python3 scripts/extract_schema.py workflow_api.json --summary-only
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}

python3 scripts/extract_schema.py workflow_api.json
# → full schema with parameters, model deps, embedding refs
```

### Step 7: Check Dependencies

```bash
python3 scripts/check_deps.py workflow_api.json
# → are this workflow's nodes/models/embeddings installed?

python3 scripts/auto_fix_deps.py workflow_api.json
# → auto-install missing nodes and models
```

### Step 8: Run the Workflow

```bash
# Local (defaults to http://127.0.0.1:8188)
python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
  --output-dir ./outputs

# Cloud (export API key once; uses correct /api routing automatically)
export COMFY_CLOUD_API_KEY="comfyui-..."
python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "..."}' \
  --host https://cloud.comfy.org \
  --output-dir ./outputs

# Real-time progress via WebSocket (requires `pip install websocket-client`)
python3 scripts/run_workflow.py \
  --workflow flux_dev.json \
  --args '{"prompt": "..."}' \
  --ws

# img2img / inpaint: pass --input-image to upload + reference automatically
python3 scripts/run_workflow.py \
  --workflow sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it watercolor", "denoise": 0.6}'

# Inpainting: pass both image and mask
python3 scripts/run_workflow.py \
  --workflow sdxl_inpaint.json \
  --input-image image=./photo.png \
  --input-image mask_image=./mask.png \
  --args '{"prompt": "fill with flowers"}'

# Batch / sweep: 8 random seeds, parallel up to cloud tier limit
python3 scripts/run_batch.py \
  --workflow sdxl.json \
  --args '{"prompt": "abstract"}' \
  --count 8 --randomize-seed --parallel 3 \
  --output-dir ./outputs/batch
```

`-1` for `seed` (or omitting it with `--randomize-seed`) generates a fresh random seed per run. The actual seed is logged to stderr.

### Step 9: Present Results

The scripts emit JSON to stdout describing every output file:

```json
{
  "status": "success",
  "prompt_id": "abc-123",
  "outputs": [
    {"file": "./outputs/sdxl_00001_.png", "node_id": "9",
     "type": "image", "filename": "sdxl_00001_.png"}
  ]
}
```

### Image Upload (img2img / Inpainting)

Manual upload via REST:

```bash
curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
# Returns: {"name": "photo.png", "subfolder": "", "type": "input"}

# Cloud equivalent:
curl -X POST "https://cloud.comfy.org/api/upload/image" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
```

### Queue & System Management

```bash
# Local
curl -s http://127.0.0.1:8188/queue | python3 -m json.tool
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'    # cancel pending
curl -X POST http://127.0.0.1:8188/interrupt                      # cancel running
curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

# Cloud — same paths under /api/, plus:
python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
```

### Cloud Specifics

- **Base URL:** `https://cloud.comfy.org`
- **Auth:** `X-API-Key` header (or `?token=KEY` for WebSocket)
- **API key:** set `$COMFY_CLOUD_API_KEY` once and the scripts pick it up automatically
- **Output download:** `/api/view` returns a 302 to a signed URL; the scripts follow it and strip `X-API-Key` before fetching from the storage backend (don't leak the API key to S3/CloudFront)
- **Endpoint differences from local ComfyUI:**
  - `/api/object_info`, `/api/queue`, `/api/userdata` — 403 on free tier; paid only
  - `/history` is renamed to `/history_v2` on cloud (scripts route automatically)
  - `/models/<folder>` is renamed to `/experiment/models/<folder>` on cloud (scripts route automatically)
  - `clientId` in WebSocket is currently ignored — all connections for a user receive the same broadcast. Filter by `prompt_id` client-side.
  - `subfolder` is accepted on uploads but ignored — cloud has a flat namespace
- **Concurrent jobs:** Free/Standard: 1, Creator: 3, Pro: 5. Extras queue automatically. Use `run_batch.py --parallel N` to saturate your tier.

### Decision Tree

| User says | Tool | Command |
|-----------|------|---------|
| **Lifecycle (use comfy-cli)** | | |
| "install ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
| "start ComfyUI" | comfy-cli | `comfy launch --background` |
| "stop ComfyUI" | comfy-cli | `comfy stop` |
| "install X node" | comfy-cli | `comfy node install <name>` |
| "download X model" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
| "list installed models" | comfy-cli | `comfy model list` |
| "list installed nodes" | comfy-cli | `comfy node show installed` |
| **Execution (use scripts)** | | |
| "is everything ready?" | script | `health_check.py` (optionally with `--workflow X --smoke-test`) |
| "what can I change in this workflow?" | script | `extract_schema.py W.json` |
| "check if W's deps are met" | script | `check_deps.py W.json` |
| "fix missing deps" | script | `auto_fix_deps.py W.json` |
| "generate an image" | script | `run_workflow.py --workflow W --args '{...}'` |
| "use this image" (img2img) | script | `run_workflow.py --input-image image=./x.png ...` |
| "8 variations with random seeds" | script | `run_batch.py --count 8 --randomize-seed ...` |
| "show me live progress" | script | `ws_monitor.py --prompt-id <id>` |
| "fetch the error from job X" | script | `fetch_logs.py <prompt_id>` |
| **Direct REST** | | |
| "what's in the queue?" | REST | `curl http://HOST:8188/queue` (local) or `--host https://cloud.comfy.org` |
| "cancel that" | REST | `curl -X POST http://HOST:8188/interrupt` |
| "free GPU memory" | REST | `curl -X POST http://HOST:8188/free` |

## Pitfalls

1. **API format required** — every script and the `/api/prompt` endpoint expect API-format workflow JSON. The scripts detect editor format (top-level `nodes` and `links` arrays) and tell you to re-export via "Workflow → Export (API)" (newer UI) or "Save (API Format)" (older UI).

2. **Server must be running** — all execution requires a live server. `comfy launch --background` starts one. Verify with `curl http://127.0.0.1:8188/system_stats`.

3. **Model names are exact** — case-sensitive, includes file extension. `check_deps.py` does fuzzy matching (with/without extension and folder prefix), but the workflow itself must use the canonical name. Use `comfy model list` to discover what's installed.

4. **Missing custom nodes** — "class_type not found" means a required node isn't installed. `check_deps.py` reports which package to install; `auto_fix_deps.py` runs the install for you.

5. **Working directory** — `comfy-cli` auto-detects the ComfyUI workspace. If commands fail with "no workspace found", use `comfy --workspace /path/to/ComfyUI <command>` or `comfy set-default /path/to/ComfyUI`.

6. **Cloud free-tier API limits** — `/api/prompt`, `/api/view`, `/api/upload/*`, `/api/object_info` all return 403 on free accounts. `health_check.py` and `check_deps.py` handle this gracefully and surface a clear message.

7. **Timeout for video/audio workflows** — auto-detected when an output node is `VHS_VideoCombine`, `SaveVideo`, etc.; the default jumps from 300 s to 900 s. Override explicitly with `--timeout 1800`.

8. **Path traversal in output filenames** — server-supplied filenames are passed through `safe_path_join` to refuse anything escaping `--output-dir`. Keep this protection on — workflows with custom save nodes can produce arbitrary paths.

9. **Workflow JSON is arbitrary code** — custom nodes run Python, so submitting an unknown workflow has the same trust profile as `eval`. Inspect workflows from untrusted sources before running.

10. **Auto-randomized seed** — pass `seed: -1` in `--args` (or use `--randomize-seed` and omit the seed) to get a fresh seed per run. The actual seed is logged to stderr.

11. **`tracking` prompt** — first run of `comfy` may prompt for analytics. Use `comfy --skip-prompt tracking disable` to skip non-interactively. `comfyui_setup.sh` does this for you.

## Verification

Use `python3 scripts/health_check.py` to run the whole checklist at once. Manual checks:

1. `hardware_check.py` verdict is `ok` OR the user explicitly chose Comfy Cloud
2. `comfy --version` works (or `uvx --from comfy-cli comfy --help`)
3. `curl http://HOST:PORT/system_stats` returns JSON
4. `comfy model list` shows at least one checkpoint (local) OR `/api/experiment/models/checkpoints` returns models (cloud)
5. Workflow JSON is in API format (each node has `class_type`, not top-level `nodes`/`links` arrays)
6. `check_deps.py` reports `is_ready: true` (or only `node_check_skipped` on cloud free tier)
7. Test run with a small workflow completes; outputs land in `--output-dir`:

```bash
python3 scripts/run_workflow.py \
  --workflow workflows/sd15_txt2img.json \
  --args '{"prompt": "test", "steps": 4}' \
  --output-dir ./test-outputs
```

## Related skills

- `stable-diffusion-image-generation`
- `image_gen`