I have a pug dog to maintain and he does not eat or drink or play with fresh air!

Boyo-IRIS3B — ComfyUI Node Pack

ComfyUI custom nodes wrapping speridlabs/iris-3b. Sequential VRAM management — only one 12 GB model loaded at a time. The iris-3b library is vendored inside this repo — no submodules, no separate clones.

---

Nodes

---

Installation

cd ComfyUI/custom_nodes
git clone https://github.com/DragonDiffusionbyBoyo/Boyo-IRIS3B-Comfyui.git
cd Boyo-IRIS3B-Comfyui
pip install -r requirements.txt
pip install -e iris-3b/

Restart ComfyUI.

---

First run — download models

Add an Iris-3B Download Models node to your workflow and queue it once. It downloads everything into ComfyUI's models folder:

ComfyUI/models/
    iris3b/
        manifest.json
        config.yaml
        model.safetensors              (~12 GB — generation model)
        depth/
            model.safetensors          (~12 GB — depth fine-tune)
        upscaler/
            model.safetensors          (~12 GB — upscaler fine-tune)
    text_encoders/
        Qwen3-VL-4B-Instruct/
            model-00001-of-00002.safetensors   (~4 GB each)
            model-00002-of-00002.safetensors
            ... (tokeniser and config files)

Total: ~40 GB. Subsequent runs skip the download entirely (manifest check).

---

Typical workflow

[Iris-3B Model Loader]
        │ IRIS3B_MODEL
        ▼
[Iris-3B Generate] ──── IMAGE ────┬──► [Preview Image]
                                  ├──► [Iris-3B Depth]   ──► [Preview Image]
                                  └──► [Iris-3B Upscale] ──► [Save Image]

The upscaler accepts any image — not just Iris-3B outputs. Plug any external image straight into it.

---

Generation — working resolutions

Square resolutions below 1024×1024 produce artefacts due to the pixel decoder. Use these:

---

Upscaler

One-step 4× restoration fine-tune. Works on any input image.

• scale — upscale factor, 4× is optimal (trained resolution)
• color_fix — wavelet colour fix keeps detail but takes colour from bicubic reference
• fit_budget — downscales input before upscaling to cap tile count. Off by default
• short_side_cap / long_side_cap — budget limits when fit_budget is on

Tile count scales with output area. At 4× scale:

• 512×768 input → 2048×3072 output → ~18 tiles
• 832×1280 input → 3328×5120 output → ~50 tiles

---

VRAM usage

Between stages: ~0 GB (CPU offloaded, cache cleared).

---

LoRA support

Point the Iris-3B Model Loader at any LoRA produced by AI-Toolkit as a .safetensors file. Merged in weight-space before inference, discarded afterwards.

---

Environment variables