MonarchRT Doctor

Most ComfyUI packs fail by throwing a stack trace at you from four layers deep in a library you've never heard of. This pack fails differently: it runs your video generation in a separate Python environment, outside ComfyUI entirely, across a WSL2 boundary. When something goes wrong there, ComfyUI sees almost nothing. That's the gap the Doctor fills - and if you're setting this up for the first time, it's the second thing you queue, right after realising the runtime exists at all.

What it actually checks

Under the hood it launches runtime/monarchrt_doctor.py with the runtime's own Python and reads back a JSON report. Nothing touches your ComfyUI install, and with both toggles off it's cheap. The checks it reports:

• upstream_commit and upstream_files - the git HEAD of the pinned MonarchRT checkout, plus the sha256 of the specific upstream files this integration depends on. A HEAD mismatch is a warn; a modified or missing file is a fail. This is how you catch "I cloned upstream and left it on master" and "I edited the kernel to see what happens".
• model_files - every required weight file, checked for presence and byte size, plus sha256 if you asked.
• cuda - device name, compute capability, free and total VRAM. Under 40 GB without offload_text_encoder: true, it warns rather than fails: that config still runs, it just spills into shared system memory.
• import: rows for triton, flash_attn, flashinfer, diffusers, transformers, omegaconf, av, einops - each reports its version or the import error. This is where "the venv is missing flash-attn" stops being a mystery.
• triton_kernel - a tiny Triton kernel that adds two tensors, which exercises the C compiler Triton needs for its launcher. When this fails, it's almost always a missing compiler, not a broken GPU.
• monarch_kernel - only with kernel_check on. It compares the Monarch Triton kernel against its torch reference at the real inference geometry, for both h_reduce=2 and h_reduce=1, and reports cosine similarity and whether bf16 values agree. It's skipped if upstream files or CUDA already failed.

The node also appends the persistent worker's status, so you get "is a warm process holding my GPU" in the same report.

The three inputs

• runtime_id - the same enum the Runtime node shows, read from ComfyUI/user/monarchrt.runtimes.json. Administrator config, not workflow config.
• verify_sha256 (default off) - hashes every model file. The tooltip's own warning is worth heeding: about 23 GB of reads. Run it once, after a download you're unsure about, then leave it off.
• kernel_check (default off) - the kernel-versus-reference comparison. The first run tunes kernels, so budget a few minutes. This is the check that tells you the Monarch kernels are correct on your card and driver, which no version number can tell you.

Output is a single report STRING. The node is an output node, so queueing it runs it, and it prints a short summary in the node's UI text area - one line per check, prefixed ok/warn/fail, headed by the runtime name and an overall verdict. Wire report to Preview Any for the full JSON. It also re-checks every time it's queued rather than being cached, which is what you want from a diagnostic.

Install

Same pack as everything else, so nothing extra:

cd ComfyUI/custom_nodes
git clone https://github.com/hiroki-abe-58/ComfyUI-MonarchRT

or install MonarchRT from ComfyUI Manager. The node itself adds no Python packages to ComfyUI. There's a ready-made workflow at workflows/monarchrt_doctor.json if you'd rather not build it.

What it cannot fix is the runtime not existing yet. If you haven't done docs/SETUP.md - the Python 3.10 venv, torch 2.8.0+cu128, the flash-attn and flashinfer wheels, the pinned upstream checkout and the ~23 GB of weights - there is nothing to diagnose.

Reading the result like an adult

fail on import:triton or triton_kernel - install build-essential in the distro, or use the zig wrapper from SETUP.md as CC. Triton compiles a C launcher on first use; no GPU can save you from a missing compiler.

warn on upstream_commit with ok on upstream_files - you're on a different commit but the files that matter are byte-identical. Usually fine, occasionally not. Rerun after checking out the pinned revision 34867c04….

fail on model_files with a size mismatch - an interrupted download. Delete the file and re-fetch at the pinned revision.

vram warn - the 11 GB UMT5-XXL encoder is staying resident. Set offload_text_encoder: true in the runtime config. On a 32 GB card, without it, the box starts swapping and the failure looks like a slow hang, not an error.

monarch_kernel fails but everything else is green - stop and read it. There's no silent fallback in the generation path: the runner fails the job if any self-attention call doesn't go through the kernel the profile asks for, so a broken kernel isn't a quality problem, it's a this-won't-run problem.