| Headless / server / CI / agents | **Path D: comfy-cli** |
For the fully automated path (hardware check → install → launch → verify):
bash scripts/comfyui_setup.sh
# Or with overrides:
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
It 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.
Docs: https://docs.comfy.org/get_started/cloud
Sign up at https://comfy.org/cloud
Generate an API key at https://platform.comfy.org/login
Set the key:
export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
Run workflows:
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.
Docs: https://docs.comfy.org/installation/desktop
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)
Docs: https://docs.comfy.org/installation/comfyui_portable_windows
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)
The official CLI is the best path for headless/automated setups.
Docs: https://docs.comfy.org/comfy-cli/getting-started
Install comfy-cli
# 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:
comfy --skip-prompt tracking disable
Install ComfyUI
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 / verify
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.
Docs: https://docs.comfy.org/installation/manual_install
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
---
Post-Install: Download Models
# 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.
Post-Install: Install Custom Nodes
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
Post-Install: Verify
python3 scripts/health_check.py
# → comfy_cli on PATH? server reachable? checkpoints? smoke test?
python3 scripts/check_deps.py my_workflow.json
# → are this workflow's nodes/models/embeddings installed?
python3 scripts/run_workflow.py
--workflow workflows/sd15_txt2img.json
--args '{"prompt": "test", "steps": 4}'
--output-dir ./test-outputs
Image Upload (img2img / Inpainting)
The simplest way is to use --input-image with run_workflow.py:
python3 scripts/run_workflow.py
--workflow workflows/sdxl_img2img.json
--input-image image=./photo.png
--args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
The flag uploads photo.png, then injects its server-side filename into
whatever schema parameter is named image. For inpainting, pass both:
python3 scripts/run_workflow.py
--workflow workflows/sdxl_inpaint.json
--input-image image=./photo.png
--input-image mask_image=./mask.png
--args '{"prompt": "fill with flowers"}'
Manual upload via REST:
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"
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 (the scripts route
automatically).
/models/ is renamed to /experiment/models/ on cloud
(the 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.
Queue & System Management
# 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
Pitfalls
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).
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.
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.
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.
Working directory — comfy-cli auto-detects the ComfyUI workspace.
If commands fail with "no workspace found", use
comfy --workspace /path/to/ComfyUI or
comfy set-default /path/to/ComfyUI.
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.
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.
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.
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.
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.
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 Checklist
Use python3 scripts/health_check.py to run the whole list at once. Manual:
[ ] hardware_check.py verdict is ok OR the user explicitly chose Comfy Cloud
[ ] comfy --version works (or uvx --from comfy-cli comfy --help)
[ ] curl http://HOST:PORT/system_stats returns JSON
[ ] comfy model list shows at least one checkpoint (local) OR
/api/experiment/models/checkpoints returns models (cloud)
[ ] Workflow JSON is in API format
[ ] check_deps.py reports is_ready: true (or only node_check_skipped
on cloud free tier)
[ ] Test run with a small workflow completes; outputs land in --output-dir
