🦊 Kumiho Load Asset

Kumiho Load Asset is the input half of the Kumiho pack: if your team keeps checkpoints, LoRAs and final renders in Kumiho Cloud, this is how they come back into a workflow. You hand it a kref:// reference or a couple of name fields, and it hands you a local file path. That last word matters more than people expect - this node returns a path string, not an IMAGE tensor, so it does not plug straight into a KSampler. You wire its file_path into a loader that reads from a path, and you're in business.

How it works

The whole Kumiho system is built on BYO storage: your files never leave your disk, and the cloud only tracks references to them. Load Asset is where that promise pays off. It resolves a reference like kref://ComfyUI@KumihoClouds/checkpoint/flux/flux1-schnell.checkpoint?r=latest&a=fp8 down to an actual file by asking the SDK for the item, grabbing the revision, and reading the artifact's location field - which is a real path on your machine. No download unless the file is genuinely missing locally.

You get two ways to tell it what you want, and they stack:

• Direct kref. Paste the whole kref_uri in and it overrides everything else. The format is kref://project/space/item.kind?r=revision&a=artifact_type - the ?r= part can be a number or a tag like latest or published.
• Component mode. Leave kref_uri blank and fill item_name + item_kind. The node builds the kref for you, using space if you give it one or guessing a sensible default from the kind (checkpoint → checkpoint/…, lora → lora/…).

The tag / revision field picks a specific revision (blank = latest), and artifact_name selects which artifact of that revision - useful when a revision carries both a preview and a full-res file. project defaults to [Auto], which uses your configured project; pick one explicitly if you juggle several.

The one input beginners sleep on is fallback_file_path. If resolution fails - item missing, wrong kind, no auth - the node falls back to this local path instead of returning an empty string. During setup it turns a hard error into a workflow that still runs.

Outputs

• file_path - resolved local path (STRING). Feed it to a path-reading loader.
• kref - the exact kref that resolved, handy to feed into a Save node for lineage.
• metadata - a JSON blob with status (resolved, fallback, unresolved, error) plus what actually resolved. When something's wrong, read this first; it tells you exactly where it gave up.

One quirk: the node re-executes on every run (its IS_CHANGED returns float("NaN"), the canonical "always rerun" trick from the plumbing playbook). That's deliberate - assets can change in the cloud between runs, so caching would silently hand you stale paths.

Install

It ships in the kumiho-comfyui pack. Easiest: ComfyUI Manager → Install Custom Nodes → search "Kumiho". Or:

cd ComfyUI/custom_nodes
git clone https://github.com/kumihoclouds/kumiho-comfyui
pip install -r kumiho-comfyui/requirements.txt

No model files. The real dependency is the Kumiho SDK plus the CLI for auth, and auth is the step everyone forgets:

pip install kumiho-cli
kumiho-cli login     # opens a browser for OAuth
kumiho-cli whoami    # verify before touching a node

That writes ~/.kumiho/kumiho_authentication.json, which the SDK discovers on import. Make sure the SDK landed in the same Python environment ComfyUI runs - the classic failure here is a pack that imported fine but an SDK installed into a different venv.

Common issues

The metadata output is your debugger. status: error or unresolved with an empty file_path almost always means one of three things: you're not authenticated (kumiho-cli whoami to check), the kref's item doesn't exist or has no artifacts (the source literally logs "Item not found"), or the kind doesn't match what's actually registered. The item name in a kref is case-sensitive and includes the .kind suffix - hero.Model and hero.model are different items. And remember the [Auto] project resolves to your tenant's default, so an asset saved under a different project won't resolve unless you pick it.