Skip to content

AGENTS.md

Latest commit

 

History

History
29 lines (20 loc) · 2.19 KB

AGENTS.md

File metadata and controls

29 lines (20 loc) · 2.19 KB
Raw

Non-obvious constraints

  • No hot-reload: handler.py, start.sh, and network_volume.py are ADDed into the Docker image at build time (to /). Any change requires a full docker build before testing with docker-compose.
  • Platform mismatch: Always build with --platform linux/amd64 for Runpod deployment. Omitting this on ARM hosts (Apple Silicon) produces images that silently fail on Runpod.
  • No linter or formatter configured: Follow PEP 8 by convention; there are no pre-commit hooks or CI lint checks.
  • ComfyUI-Manager forced offline: start.sh calls comfy-manager-set-mode offline on every boot. Custom nodes cannot be installed at runtime through the Manager UI — they must be baked into the Docker image.
  • Network volume mount point: Models on a network volume must match the directory structure in src/extra_model_paths.yaml. The volume is expected at /runpod-volume with a comfyui/models/ subtree.

Model type detection (for workflow parsing)

Node types map to model directories — this is ComfyUI domain knowledge not encoded in handler code:

  • UpscaleModelLoader → upscale_models
  • VAELoader → vae
  • UNETLoader, UnetLoaderGGUF, Hy3DModelLoader → diffusion_models
  • DualCLIPLoader, TripleCLIPLoader → text_encoders
  • LoraLoader → loras

Custom node compatibility

Some custom nodes have dependency conflicts that only surface at runtime:

  • ComfyUI-BrushNet: Requires diffusers>=0.29.0, accelerate>=0.29.0,<0.32.0, and peft>=0.7.0. Without these exact ranges, you get silent import errors.
  • General pattern: When a custom node fails with import errors, check its dependency chain and pin versions in the Dockerfile with uv pip install.