ComfyUI-LM-Remote/README.md

# ComfyUI-LM-Remote

Remote-aware [LoRA Manager](https://github.com/willmiao/ComfyUI-Lora-Manager) nodes for ComfyUI. Fetches metadata (trigger words, hashes, model info) from a remote LoRA Manager instance via HTTP, while loading LoRA files from local NFS/SMB-mounted paths.

## Why?

When ComfyUI runs on a GPU workstation and LoRA Manager runs in Docker on a NAS (e.g., Unraid), the original LoRA Manager nodes can't access the remote metadata database. This package bridges that gap:

- **Proxy middleware** transparently forwards the LoRA Manager web UI and API to the remote instance
- **Remote nodes** fetch metadata via HTTP instead of local SQLite lookups
- **Local file loading** is unchanged -- LoRA files are loaded from shared storage (NFS/SMB)

```
ComfyUI Workstation                        NAS (Docker)
+--------------------------+              +------------------------+
| ComfyUI                  |              | LoRA Manager           |
|  +- ComfyUI-LM-Remote   |   HTTP API   |  +- SQLite metadata DB |
|  |  (this package)       |<------------>|  +- CivitAI sync       |
|  +- /mnt/loras/ (NFS)   |              |  +- Port 8188          |
+--------------------------+              +------------------------+
         |                                           |
         +------- Shared NFS/SMB storage ------------+
```

## Prerequisites

- A running LoRA Manager instance accessible over the network (e.g., in Docker)
- Shared storage so both machines see the same LoRA files at compatible paths

> **Note:** The original [ComfyUI-Lora-Manager](https://github.com/willmiao/ComfyUI-Lora-Manager) package is **not required**. Widget JS files and Vue widget types are served from the remote instance via the proxy. You may still install it alongside if you want the original (non-remote) nodes available too.

## Installation

Clone into your ComfyUI `custom_nodes/` directory:

```bash
cd /path/to/ComfyUI/custom_nodes/
git clone https://github.com/ethanfel/ComfyUI-LM-Remote.git
```

## Configuration

Open the configuration panel from any of these places:

- Click the gear in the **LoRA Info** sidebar
- Open **Settings**, select **LM Remote**, then click **Configure LM Remote**
- Run **Configure LM Remote** from the command palette

Enter the remote URL, adjust the timeout if needed, and click **Test connection**. **Save** validates the settings and applies them to new requests immediately; the ComfyUI process does not need to restart. If the remote URL changes, the panel offers a page reload so Manager assets and live progress reconnect to the new server. Save workflow edits before using it.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `remote_url` | string | `""` | URL of the remote LoRA Manager instance |
| `timeout` | int | `30` | HTTP request timeout in seconds |
| `path_mappings` | object | `{}` | Remote-to-local path prefix mapping (see below) |

Configuration is stored under `<ComfyUI user directory>/ComfyUI-LM-Remote/config.json`, outside the custom-node checkout. An existing package-level `config.json` is loaded as a legacy fallback and is left untouched. The first save through the panel migrates its values into ComfyUI user data.

The panel is the normal way to manage this file; manual editing is not required. For a headless or automated deployment, start from [`config.example.json`](config.example.json), place the copy outside the custom-node checkout, and point `LM_REMOTE_CONFIG` to it.

### Environment Variable Overrides

Environment variables take priority over the stored configuration without rewriting it. Overridden fields are shown as managed in the panel.

| Variable | Purpose |
|----------|---------|
| `LM_REMOTE_URL` | Overrides `remote_url`; the field is shown as managed in the panel |
| `LM_REMOTE_TIMEOUT` | Overrides `timeout`; the field is shown as managed in the panel |
| `LM_REMOTE_CONFIG` | Uses an explicit configuration file instead of the ComfyUI user-data path |

### Path Mappings

If the remote instance and local ComfyUI see LoRA files at different absolute paths, use `path_mappings` to translate:

```json
{
    "path_mappings": {
        "/data/models/loras": "/mnt/nas/models/loras"
    }
}
```

This maps the remote path prefix `/data/models/loras` to the local `/mnt/nas/models/loras`. Usually not needed if both machines use the same NFS mount point.

## Nodes

All nodes appear under the **Lora Manager** category in the ComfyUI node menu, with "(Remote, LoraManager)" in the name.

| Node | Description |
|------|-------------|
| **Lora Loader (Remote)** | Load LoRAs with trigger words from remote metadata. Supports Nunchaku Flux models. |
| **LoRA Text Loader (Remote)** | Load LoRAs from `<lora:name:strength>` text syntax. |
| **Lora Stacker (Remote)** | Stack multiple LoRAs into a LORA_STACK for downstream loaders. |
| **Lora Randomizer (Remote)** | Randomly sample LoRAs from the remote pool with configurable count and strength ranges. |
| **Lora Cycler (Remote)** | Sequentially cycle through LoRAs from the remote pool. |
| **Lora Pool (Remote)** | Configure pool filters (base model, tags, folders, favorites) for Randomizer/Cycler. |
| **Save Image (Remote)** | Save images with embedded generation metadata, using remote hash lookups for LoRA and checkpoint hashes. |
| **WanVideo Lora Select (Remote)** | Select LoRAs for WanVideo with block-level control. |
| **WanVideo Lora Select From Text (Remote)** | Select WanVideo LoRAs from text syntax. |

## LoRA Info Sidebar

Selecting a LoRA loader opens the **LoRA Info** sidebar and follows the node's current selection. It supports the stock ComfyUI loader, LM Remote nodes, and third-party loaders that expose standard `lora_name`, numbered LoRA, stack, or `<lora:name:strength>` values.

- If the selected LoRA is indexed by the remote LoRA Manager, the sidebar shows its preview, file details, base model, trigger words, tags, usage tips, and direct model links.
- If a node contains multiple active LoRAs, use the selector at the top of the sidebar to switch cards.
- If no Manager card exists, the sidebar offers name searches on LoRA Manager, Civitai, Civitai Red, and CivArchive.
- Duplicate filenames are not guessed: the sidebar asks you to choose the matching Manager path.

ComfyUI does not currently expose an extension API for adding custom tabs to the built-in Properties panel, so this feature uses its supported custom-sidebar API. It follows ComfyUI's configured sidebar location, including a right-side layout like Templates.

Auto-open is enabled by default. Disable it under **Settings > LM Remote > LoRA Info > Auto-open** if you prefer to open **LoRA Info** manually from the sidebar or command palette.

The gear beside the refresh button opens LM Remote connection settings without leaving the sidebar.

## How It Works

### Reverse Proxy

An aiohttp middleware is registered at startup that intercepts requests to LoRA Manager endpoints and forwards them to the remote instance:

**Proxied routes:**
- `/api/lm/*` -- all REST API endpoints (except send_sync routes below)
- `/extensions/ComfyUI-Lora-Manager/*` -- widget JS files and Vue widget bundle
- `/loras_static/*`, `/locales/*`, `/example_images_static/*` -- static assets
- `/loras`, `/checkpoints`, `/embeddings`, `/loras/recipes`, `/community`, `/statistics` -- web UI pages
- `/ws/fetch-progress`, `/ws/download-progress`, `/ws/init-progress` -- WebSocket connections

**Handled locally** (events broadcast to local browser via `send_sync`):
- `/api/lm/loras/get_trigger_words` -- fetches trigger words from remote, broadcasts `trigger_word_update`
- `/api/lm/update-lora-code` -- broadcasts `lora_code_update`
- `/api/lm/update-node-widget` -- broadcasts `lm_widget_update`
- `/api/lm/register-nodes` -- no-op in remote mode

### Remote Metadata

Nodes use `RemoteLoraClient` to fetch metadata from the remote LoRA Manager API. A 60-second in-memory cache avoids redundant API calls during workflow execution. The client queries:

- `GET /api/lm/loras/list` -- full LoRA list (cached)
- `GET /api/lm/loras/get-trigger-words` -- trigger words fallback
- `POST /api/lm/loras/random-sample` -- random sampling
- `POST /api/lm/loras/cycler-list` -- cycler ordering
- `GET /api/lm/checkpoints/list` -- checkpoint hashes (cached)

### Local File Loading

After fetching the relative path from the remote metadata, LoRA files are loaded locally via `folder_paths.get_full_path("loras", relative_path)`. No files are transferred over the network.

## Verification

After installation and configuration:

1. Restart ComfyUI once after installing the custom node
2. Open **Configure LM Remote**, enter the URL, and run **Test connection**
3. Save the configuration; no ComfyUI process restart is required
4. If prompted after a remote URL change, save workflow edits and reload the browser page
5. Open the LoRA Manager web UI -- it should load through the remote proxy
6. Add a stock or remote LoRA loader and click the node -- **LoRA Info** should open
7. Select a LoRA -- its Manager card (or external search links) should appear and remote trigger words should populate where supported
8. Run the workflow -- the LoRA loads from local shared storage

## License

Same license as [ComfyUI-Lora-Manager](https://github.com/willmiao/ComfyUI-Lora-Manager).