ComfyUI-PixlStash
Custom ComfyUI nodes for loading and saving images to a PixlStash vault.
Nodes (14)
The PixlStash Adapter Loader
The character dropdown that feeds your face-likeness gate and your saver
The PixlStash checkpoint loader that refuses to download anything
One CLIP loader to replace both of ComfyUI's
The node that kills bad character renders before you upscale them
Give it a reference image (or four), get back the vault's closest lookalikes
Keep only frames that match a reference set
Pull vault images into ComfyUI as tensors — browse them, or just let the filters decide
Save generations straight back into your vault — with the workflow baked into the PNG
One dropdown that scopes your whole PixlStash workflow
'red dress at golden hour' just works
The Set Loader does the scoping for you
The PixlStash VAE loader, and why TAESD never shows up in its grid
The PixlStash Workflow Set Loader, and the one thing it won't do
<div align="center"> <a href="examples/PixlStash-SearchImageEdit.json"><img src="screenshots/ScreenshotSearchEdit.jpg" alt="Semantic search feeding a ComfyUI image-edit pipeline" width="100%"></a> <p><sub>Semantic search to image edit, end to end. <a href="examples/PixlStash-SearchImageEdit.json">Open this workflow</a>.</sub></p> </div>
Overview
These nodes connect ComfyUI to a PixlStash vault. Load images by project, set or character, run them through any pipeline, and save the results back with metadata. Models can be loaded from the PixlStash model shelf too.
Set the URL and API token once in ComfyUI Settings > PixlStash. The nodes read them at runtime, so they never end up in saved workflow JSON.
Nodes
| Node | What it does | Added in | Needs PixlStash |
|---|---|---|---|
| Project Loader | Picks a project. Outputs a wire to scope other nodes. | 1.0 | 1.0 |
| Set Loader | Picks a set inside a project. | 1.0 | 1.0 |
| Character Loader | Picks a character. | 1.0 | 1.2.1 |
| Picture Loader | Loads images as IMAGE and MASK. Pick them in a thumbnail browser, or leave the selection empty to fetch everything matching the wired filters. | 1.0 | 1.0 |
| Picture Saver | Uploads images, optionally filed under a project, set or character. Can embed the workflow in PNGs. | 1.0 | 1.0 |
| Likeness Search | Finds pictures by facial or image similarity to reference images. | 1.1 | 1.4 |
| Semantic Search | Finds pictures by text. | 1.1 | 1.4 |
| Face Likeness Gate | Splits a batch into accepted and rejected by how well each face matches a character. | 1.2 | 1.6 |
| Picture Likeness Gate | Same, judged on whole-image likeness to a reference picture set. | 1.3.1 | 1.4 |
| Adapter (LoRA) Loader | Applies a LoRA from the model shelf. | 1.5 | 1.10 |
| Multi Adapter (LoRA) Loader | Applies several LoRAs from the model shelf, one row each, in one node. Can list people instead of files. | 1.7 | 1.12 |
| Checkpoint Loader | Loads a checkpoint from the model shelf. | 1.5 | 1.10 |
| VAE Loader | Loads a VAE from the model shelf. | 1.5 | 1.10 |
| CLIP Loader | Loads one or two text encoders from the model shelf. | 1.5 | 1.10 |
| Workflow Set Loader | Loads a workflow set's checkpoint, text encoders and VAE in one node, and narrows an Adapter Loader to the set's LoRAs. | 1.6 | 1.12 |
"Added in" is the ComfyUI-PixlStash version. The Face Likeness Gate also needs a running face-extraction worker. A node checks the server's version before its first request and refuses an older PixlStash with a message naming both versions, rather than failing on a route the server does not have yet.
The search and gate nodes take optional project, set and character inputs as filters. The loaders pass their context through, so a saver downstream needs no extra wiring.
Search
Image search takes several images at once, so you can combine concepts. "An old man and a young man drinking beer" returns four older men drinking beer:
Gates
Wire in a batch of generations plus a Character Loader (face) or Set Loader
(picture), set a threshold, and route accepted to an upscale or save branch
so you never waste compute on a bad match. Both also output
accepted_count / rejected_count and pass the reference through.
The Picture Likeness Gate's combine mode decides how per-member scores become
one verdict: min (default) means match every member of the set, max means
match any.
Both score server-side and write nothing to the vault. A read-scope token is enough.
Model shelf loaders
Pick models from a thumbnail grid instead of a dropdown of hundreds of
filenames. Each loader has the same inputs and outputs as its ComfyUI built-in,
so it drops straight into an existing graph. The Adapter Loader adds a
trigger_words output.
Once picked, the node shows the model's name and its face: a resizable thumbnail on the Adapter (LoRA) Loader, where seeing the face is the point, a row per adapter on the Multi Adapter (LoRA) Loader, and a small favicon on the others — so a graph with four loaders stays readable without any of them ballooning in size.
Wire a Set or Character Loader into the Adapter Loader to see only that character's or set's adapters.
The Multi Adapter (LoRA) Loader is the same loader for several adapters at
once, with the same model, clip and trigger_words wires; it does not take a
Set, Character or Workflow Set Loader. Each picked adapter is a row with its
picture, the person it is attached to, its trigger word (click it to copy) and
its own two strengths. The rows are applied top to bottom, exactly as that many chained
Adapter Loaders would be, and trigger_words carries every row's words in row
order. Browse opens the same grid with several cards tickable; the number
on a card is the row it will fill. Set show to People who fit and the grid
lists people instead of files: everyone with an adapter for the chosen
base_model, with a choice between their adapters when more than one fits. A
node with no rows passes the model and clip through untouched. It holds up to
eight rows, stored in the workflow as adapter_sha256, strength_model,
strength_clip, then adapter_sha256_2 and so on.
The Workflow Set Loader loads one of the workflow sets you made on the shelf:
its checkpoint, with the set's text encoders and VAE in place of the
checkpoint's own. It does not apply the set's LoRAs, since a set records no
order or strengths. Wire its pixlstash_workflow_set output into an Adapter
Loader instead, and that loader's Browse grid shows only the set's LoRAs.
The CLIP, Checkpoint and Workflow Set loaders also read .gguf files, through
a bundled copy of ComfyUI-GGUF, so
you do not need that pack installed. A GGUF text encoder can be paired with a
safetensors one. A GGUF checkpoint is a diffusion model only: its CLIP and VAE
outputs are empty, so wire those from their own loaders. The VAE and Adapter
loaders take .safetensors only.
Files are used in place when ComfyUI and PixlStash share a filesystem. Adapters,
VAEs and text encoders are otherwise fetched once and cached under
pixlstash/<sha256>.safetensors (or .gguf) in the matching models directory, verified
against the digest. Checkpoints cannot be fetched and must be readable
locally.
Note: the shelf needs an owner token. Resource-scoped share tokens get a 403.
What a run reports
A workflow says what to look for; a run resolves that to what was actually used. A Picture Loader with an empty selection picks its batch off a live query, a search node picks its off a score, and a shelf hash becomes one particular file. None of that is in the saved workflow, and re-running it tomorrow can legitimately resolve to something else.
So the Picture Loader, the two search nodes and the five shelf loaders attach
their resolution lock to their own output: the picture IDs that loaded, and
the models they were locked to. ComfyUI carries it in the executed websocket
message and keeps it in GET /history/{prompt_id}, so PixlStash can record
what went into a render without the nodes having to call anything.
Your graphs do not change: the sockets, their types and their order are the
same, and an existing workflow loads and runs exactly as before. (Under the
hood those eight nodes now return ComfyUI's {"ui": …, "result": …} form
instead of a bare tuple, which matters only if you call them from Python.)
The lock lands under a pixlstash_lock key on the node, as a list of entries:
[{"pictures": [12, 15],
"models": [{"kind": "adapter", "sha256": "…", "id": null,
"filename": "…", "display_name": null}]}]
kind is adapter, checkpoint, vae or clip. Both identifiers are always
present and either may be null: hash-addressed files have no row id, and a
checkpoint's sha256 stays null until the shelf has hashed it. filename and
display_name are the shelf's names for the file, either null — for showing,
and for finding the model again once its shelf row is gone, never for loading.
The model's name in the saved workflow
The shelf loaders address their file by id or digest, which names nothing once
the shelf row is merged, forgotten or deleted. So when a loader picks a file,
and again when it shows the file's name on load, it records the file in the
node's properties (the editor workflow, which a picture saved from ComfyUI
embeds):
"properties": {"pixlstash_models": [
{"input": "checkpoint_id", "kind": "checkpoint", "id": 7, "sha256": "…",
"filename": "…", "display_name": "…"}]}
input is the widget the entry describes — the CLIP Loader writes one per
slot, and the Workflow Set Loader one per file it loads (the set's first
checkpoint, its encoders and its first VAE). properties never reach the API
prompt, so this changes neither what runs nor PixlStash's structural hash of
it. They are part of the editor document, so a workflow saved before this
shows as modified the first time it opens; save it once. A run submitted as a
bare prompt has no editor graph; its lock carries the same names.
Fold every entry, don't take the first. One entry per execution of the
node, which is normally one — but a node fed from something with
OUTPUT_IS_LIST runs once per element and ComfyUI concatenates the payloads,
so the list can hold several and indexing [0] would record one resolution out
of N.
Opened from PixlStash
PixlStash's Workflow tab has an Open in ComfyUI button. A workflow opened with it is linked to the PixlStash workflow it came from:
- It opens as a saved file, in a
pixlstashfolder of your ComfyUI workflows, so Ctrl+S saves it and never asks for a filename. - Saving it saves a version in PixlStash. No question is asked in either
app, and a toast says what happened:
Saved to PixlStash: Portrait, version 4. The saves of one opening are one version there, so the workflow as it was before you opened it is one step back however often you press Ctrl+S (or ComfyUI's autosave does); a version a picture was made with, or a recipe saved on, is kept. Moving nodes or re-rolling the seed is nothing new to save. If you changed the checkpoint, the save lands as a new workflow and the canvas is linked to that one from then on. If PixlStash cannot be reached, or a node will not convert, the toast says why; the file is saved in ComfyUI, the next save tries again, and until one gets through, opening the workflow from PixlStash again will not write over that file. - Only that file saves back. ComfyUI writes a workflow's link into every picture it makes and every duplicate of its tab. A picture dragged back in, a duplicated tab, a renamed file or somebody else's file is told that saving it does not save to PixlStash; PixlStash > Save to PixlStash sends it over the workflow it names if that is what you mean, and Export to PixlStash sends it as a new one.
- Your layout comes back. Positions, groups and notes are kept with the workflow, and the next Open in ComfyUI opens it the way you left it, with the workflow's current values written over it. The layout is used only when it turns out to be the same graph PixlStash has; a workflow never saved from ComfyUI, or rewired in PixlStash since, opens auto-arranged.
- A loader for people is put beside the model: a Multi Adapter Loader set
to People who fit, offering the people PixlStash's Run popup offers for
the workflow, wired where a run from PixlStash would put a person's LoRA.
Pick one or several and queue. Nobody is picked when it opens, and what you
pick is never saved into the workflow:
Nothing new to save. The people picked here stay in ComfyUI.A person's LoRA in an ordinary loader is left out of the workflow too, and the toast names it. - Save As makes a copy that is not linked. Use Export to PixlStash to send a copy, or any other workflow, to PixlStash as a new workflow.
The save is sent when ComfyUI's own save finishes, by watching the workflow
store's saveWorkflow action. That is ComfyUI's internal interface (checked
against frontend 1.53), so on a ComfyUI where it is missing a toast says so
once, and PixlStash > Save to PixlStash in the menu sends the canvas by
hand. Autosave makes the same call as Ctrl+S, so it is sent like any save.
Needs a PixlStash new enough to keep versions of a workflow, and an owner token in Settings > PixlStash.
Export to PixlStash
A workflow in ComfyUI is an editor document, and only ComfyUI can turn it into a graph PixlStash can run. Open the workflow, then pick PixlStash > Export to PixlStash from the menu: ComfyUI converts it and sends both to PixlStash, which can then run it and offer its parameters.
Nothing has to be saved first. What is sent is the workflow as it stands on the canvas, unsaved changes included, and ComfyUI's own file is left alone. PixlStash recognises a workflow it already holds and makes that one runnable; anything else arrives there as a new workflow. It is never a version of another workflow, also on a canvas opened from PixlStash, where it is how to get a new workflow on purpose. One that uses a node pack this ComfyUI lacks can't be converted, so it can't be exported. A LoRA attached to a person is not part of a workflow: the toast names any the canvas holds in an ordinary loader, and PixlStash runs and opens the workflow without it.
Needs PixlStash 1.12 or newer and an owner token in Settings > PixlStash.
Endpoints for PixlStash
Two routes ship dormant — nothing in this package or its UI calls them, and they are here so a future PixlStash can drive a ComfyUI it does not live on:
| Route | What it does |
|---|---|
| GET /pixlstash/inventory | This package's version, the oldest PixlStash its nodes accept, and the checkpoint / LoRA / VAE / text-encoder filenames ComfyUI can see. |
| POST /pixlstash/assets | Takes one image into ComfyUI's input directory under pixlstash/, as the first multipart field, named file — and answers with the {name, subfolder, type} a workflow needs to reference it. |
Both need Authorization: Bearer <token> carrying the API token from
Settings > PixlStash. Every /pixlstash/* route asks for that header, but
the proxy routes only forward it and let PixlStash decide; these two are
checked here, because they run locally and one of them writes a file while
ComfyUI's own server usually has nothing in front of it.
An asset's filename must be 1–128 characters of A–Z a–z 0–9, space, dot, dash
or underscore, and must end in an image extension ComfyUI can load (.png,
.jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff). The extension rule
is containment, not tidiness: ComfyUI's own /view serves anything under the
input directory back over ComfyUI's origin, so an .html or .svg there would
run as a page with read access to the settings file holding this very token.
A name that is already taken gets a 409 rather than being replaced — a prompt
sitting in ComfyUI's queue must not start loading bytes it was not submitted
against. Nothing before the file field is read, so the 64 MB ceiling cannot
be reached around by a large field in front of it.
Workflow examples
Ready-to-load JSON lives in examples/. Click a screenshot to open
its workflow.
Search to image edit. Pull images out of the vault by meaning, then edit them.
Outpaint. Extend a vault image beyond its frame.
Face Likeness Gate. Keep only the frames matching a character.
Or end to end: generate with a character LoRA, gate, upscale the matches, save both streams to separate sets.
The same pipeline with every model off the shelf:
Picture Likeness Gate. Keep only the frames matching a reference set: bare, or with upscale and save:
Upscale. Upscale a vault image and save it back with metadata intact.
Generate from the model shelf. Checkpoint, VAE and text encoder all picked from a Browse grid, render saved straight into a project.
Some of these use subgraphs, so they need a recent ComfyUI. Bare diffusion
models like Flux.2 Klein 9B and Z-Image Turbo are filed as checkpoints, so only
the Checkpoint Loader's model output is wired and clip and vae come from
their own loaders.
Installation
Search for ComfyUI-PixlStash in the ComfyUI Manager and click Install.
Or manually:
cd custom_nodes
git clone https://github.com/Pikselkroken/ComfyUI-PixlStash.git
Loading .gguf models needs the gguf Python package, which is not installed
with this pack. Run pip install -U "gguf>=0.13.0" in ComfyUI's environment if
you use GGUF models; the loader says so if it is missing or too old. A few GGUF text encoders (a Wan
UMT5, Gemma 3) also need sentencepiece and protobuf to rebuild their
tokenizer, and the error names them too.
Restart ComfyUI, then set your URL and API token under Settings > PixlStash.
Configuration
| Setting | Description | |---|---| | URL | Base URL of your PixlStash instance | | API Token | Token with the required read or write scope | | Verify SSL | Whether to validate the server certificate |
Multi-user is not supported. ComfyUI doesn't tell a node which user submitted the running prompt, so the nodes refuse to run rather than risk using someone else's token. Run one single-user ComfyUI per PixlStash user.
Development
python -m unittest discover -s tests # stdlib unittest, no ComfyUI needed
ruff check . && ruff format .
The tests stub ComfyUI's runtime modules, so only requests needs installing
(pip install -r requirements.txt). They cover the security-sensitive paths:
the multi-user guard, the proxy SSRF and auth checks, the token check and
filename containment on the two served endpoints, loader id extraction, and
path containment and digest verification in the savers and loaders.
Pull requests are reviewed by an AI reviewer (.github/workflows/ai-review.yml)
when the maintainer opens or pushes to one, or comments /review, /improve
or /ask ... on it. The rules it checks are in .github/review-context.md.
License
MIT. See LICENSE.
No ComfyUI source is copied into this repository. ComfyUI is GPL-3.0 and
this package is MIT, so everything here is written against ComfyUI's public
APIs: comfy.utils / comfy.sd for the model loaders, folder_paths,
server.PromptServer for the /pixlstash/* proxy, and app.registerExtension
plus LiteGraph for the frontend. The loaders mirror the shape of the built-ins
(inputs, outputs, widget names) so they drop into existing graphs, but none of
their code is reproduced here.
Runtime dependencies come from PyPI:
requests (Apache-2.0),
Pillow (MIT-CMU), and optionally
gguf (MIT) for GGUF models. ComfyUI supplies
torch and numpy.
Third-party code: vendor/comfyui_gguf/ is
ComfyUI-GGUF by city96, Apache-2.0,
unmodified. See vendor/comfyui_gguf/LICENSE.