The stand-in model¶

*One fake model for every model a worker holds, placed in ComfyUI's own list so its eviction can reach another process.

Why a fake model at all¶

When ComfyUI wants to load a model and the card is full, making room means walking current_loaded_models and asking each entry to unload.

An isolated pack's models live in another process, so unless something represents them in that list the host cannot evict them, cannot make space on a full card, and a pack's memory cannot be reclaimed at all.

So comfy-env puts something in the list: one stand-in for every model a worker holds (a worker that has loaded a UNet and a VAE gets two), each forwarding its own unload over IPC to the worker that holds the weights.

This is done to let two very important functions in ComfyUI operate properly: load_models_gpu (decides whether we have space to load a new model to VRAM) and free_memory (decides what to evict from VRAM if we don't have enough space).

They call out to exactly three things: - entries in that list - the pinned memory helpers - logging

There is no callback, no event and no registry on either path. The operating system cannot substitute: there is no push notification for device memory anywhere, NVML's event API has no memory bit, CUDA has no callback, and VRAM is charged to no cgroup. Host side precursors are too late; on ComfyUI's real loading path host RSS leads the device allocation by 0.1 s. That search is closed, and the stand-in stays until upstream offers a hook.

What it must answer¶

Put an object in current_loaded_models and the memory manager reads members off it, at times of its choosing, in the middle of eviction. Eighteen of them, none declared anywhere upstream:

load_device          offload_device       parent               model
model_size           loaded_size          current_loaded_device
model_dtype          model_patches_to     model_patches_models
partially_load       partially_unload     detach
lowvram_patch_counter  is_dynamic         is_clone
clone_base_uuid      get_nested_additional_models

Fourteen appear as a literal .model.<name> in the memory manager, which a grep can find. The other four (load_device, parent, model_patches_models, get_nested_additional_models) are reached through an alias or read off the incoming model, and load_device is the one upstream reads most while a literal grep sees it zero times. By purpose:

Group	Members
Identity and placement	`load_device`, `offload_device`, `parent`, `model`, `clone_base_uuid`, `is_clone`
Accounting	`model_size`, `loaded_size`, `current_loaded_device`, `model_dtype`, `lowvram_patch_counter`
Action	`partially_load`, `partially_unload`, `detach`, `model_patches_to`, `model_patches_models`
Mode	`is_dynamic`, `get_nested_additional_models`

is_dynamic is the highest leverage member. Answering False keeps the stand-in out of every pin path, out of the cast buffer reset, and out of the dynamic model bypass in the eviction loop. That last exclusion is what makes it evictable at all, and it is also the first of the three answers that are not true.

The stand-in declares that surface explicitly (COMFY_SURFACE in isolation/model_patcher.py) and does not inherit ModelPatcher; a test enforces it. Inheriting would silently import well over a hundred members that are wrong for an object holding no weights, every one of which would appear to work while returning nonsense. A duck type fails loudly on the member it lacks: its __getattr__ raises with a message naming the member and pointing at COMFY_SURFACE. The reasoning is ADR-0035.

How we know it still fits¶

A test greps upstream's model_management.py for every .model.<name> access, follows the model = entry.model alias within a function, subtracts the names that are not patcher members and the ones gated behind is_dynamic(), and asserts the remainder is a subset of COMFY_SURFACE. Upstream has no declared interface, so the test derives one from the source.

What it covers and what it does not: it runs weekly against ComfyUI master in a job marked allowed to fail, so a red run opens an issue and publishing continues. It reads one file; node code outside model_management.py also borrows the list and the canary does not look there. And it catches a missing member, while every defect found in this seam has been a wrong value on a member the stand-in implements. comfy-env has been public since 2026-04-25 and the stand-in has never raised on a user; every defect so far was a wrong number, found by review.

Why it is a compromise¶

It fails all three tests comfy-env sets for its own code.

It is not stable. It answers eighteen attributes of internals upstream never promised to keep. The eviction loop grew a whole new branch when comfy-aimdo landed; loaded_size was reimplemented for the paged patcher; the pinned memory tuple layout it must not touch moved twice in one year. None of those were breaking changes to anyone else, because none of it is an interface.

It is not correct. Three of its answers are not true, each deliberately: it says a paged model is not paged, its residency is the last receipt rather than a reading, and on Linux its size is already counted in the host's free figure. Each is priced in where the stand-in is inaccurate.

It is not easily maintainable. contract.py lists what comfy-env reads off ComfyUI, checked once before the first worker spawns. Not one entry describes what ComfyUI reads off comfy-env, which is the direction that breaks; the weekly canary above is all that covers it, and it catches a change only once the new ComfyUI is in front of us.

What this seam costs, honestly¶

On a default install every host model is managed by the pager, and the eviction loop has a bypass for those ("don't actually unload dynamic models for the sake of other dynamic models as that works on-demand"), while the stand-in reports itself non dynamic and does not get it. The worker's model can therefore be the only entry upstream evicts, and it also sorts first, because a fresh stand-in reports nothing already offloaded and the lowest possible reference count.

Two things stop that being a complaint about upstream. The bypass is a considered refusal, since evicting a paged model to make room for another paged model is churn. And for_dynamic is a parameter: comfy-env's own free_memory call leaves it False, so on the path comfy-env drives the bypass does not fire and host models are fully evictable. Where the asymmetry appears it is downstream of comfy-env's own choice to answer is_dynamic() False, the cost of the safe answer rather than a tilt in the field.

The rows it carries¶

The eleven mechanisms in the table that pass through the stand-in, with what each reads off it. Exposure is stable, fragile or broke: stable means nothing reads the stand-in on that path, fragile means the host reads internals off it that upstream has already changed once, broke means a read on that path has taken comfy-env down before.

2. `free_memory` eviction ladder¶

What ComfyUI does. free_memory eviction ladder: when the card is short, the host ranks its loaded models and asks them to leave until there is room. The rank is a four key sort (mm.py): most already offloaded first, then lowest sys.getrefcount, then smallest, and only as a final tiebreak the list index, which is newest first because load_models_gpu inserts at 0. A model it never listed is never asked.

Today. yes: ComfyUI's own eviction loop reaches the stand-in we register for each worker model, and the worker unloads. It is the only path by which upstream's own code takes memory from another process. comfy-env has three more of its own that free memory the list cannot reach: an admission time ask to idle workers (pool._ask_idle_workers), a node boundary release (pool._release_idle_workers), and a pressure hook on the stand-in's own partially_unload, which is handed the exact shortfall and posts an ask to idle siblings without blocking this loop

How exposed that leaves the stand-in. fragile: a pass reads .device, .is_dead(), .model_offloaded_memory(), .model_memory(), sys.getrefcount(.model) and .model.is_dynamic() on every candidate, then .model_unload() and .model.model.__class__.__name__ on the ones it picks (the second inside an eagerly built log string, so it runs regardless of log level). __eq__ is NOT read here: the not in keep_loaded test in mm.py runs against an empty list on every caller but unload_model_and_clones, and x not in [] compares nothing. The every-load __eq__ is row 2's. .currently_used is written here, never read; its only reader is loaded_models(). The loop body grew a dynamic branch when aimdo landed, we don't know if that might happen again in the future