Comfy Labs – Complete User Manual

Parts ©2026 Chipp Walters, Altuit, Inc.

Getting Started with Comfy-Labs

Comfy Labs is a native Windows desktop app that runs nine AI-powered creative workflows on your own NVIDIA GPU – image generation, outpainting, background removal, AI upscaling, PBR texturing, 3D mesh generation, concept art, ortho-view rendering. No cloud, no monthly fees, no accounts. Everything runs locally.

This section walks you from “I just downloaded the ZIP” to “my first workflow is running” in about 30–60 minutes (most of which is unattended download time).

What you need before you start

• Windows 10 or 11 (64-bit).
• An NVIDIA RTX GPU (RTX 30-, 40-, or 50-series). Comfy Labs does not support AMD or Intel Arc GPUs – the AI runtime requires CUDA.
• A current NVIDIA driver (any GeForce driver from late 2024 or newer; the wizard tells you the version it sees).
• An internet connection for first-run setup. After install, every workflow runs offline.
• Disk space:
  • Install drive (you pick during setup): ~21 GB for the Python runtime + ComfyUI + custom nodes. A drive other than C: is recommended, but C: is allowed if you have 25+ GB free there. (The Electron app itself, plus config.json and app.log, sit under 10 MB regardless.)
  • Models drive (you pick during setup): another 5–70 GB on top, depending on which workflows you choose. Concept Magic alone needs ~18 GB; Image to 3D Mesh adds ~9 GB; Extend Image adds ~24 GB.
• System RAM: 8 GB minimum, 32 GB recommended.

No Docker, no WSL, no Python install, no Git install required. Comfy Labs ships its own Python 3.12 runtime and a bundled MinGit binary. You just unzip the app and double-click.

Step 1 – Download and unzip

1. Get the latest Comfy-Labs-X.Y.Z.zip from the Comfy Labs distribution page.
2. Right-click the ZIP -> Properties -> check “Unblock” -> OK, then Extract All to a folder of your choice (Desktop, Documents, anywhere). The “Unblock” step prevents Windows SmartScreen from refusing to launch the app.
3. Open the extracted folder. You’ll see Comfy Labs.exe and a resources/ folder next to it. Do not move Comfy Labs.exe out of its folder – it needs the sibling resources/ tree to start.

Tip: Right-click Comfy Labs.exe -> Pin to taskbar (or Pin to Start) for one-click access later. The taskbar shortcut helper script create-shortcut.ps1 ships in the repo if you want a desktop shortcut.

Step 2 – Launch and accept SmartScreen

Double-click Comfy Labs.exe. The first launch may show a Microsoft Defender SmartScreen warning (“Windows protected your PC”) because the build is not yet code-signed.

• Click More info, then Run anyway. Comfy Labs is unsigned during the closed beta – this is expected. (Future releases will be EV-signed and the warning will go away.)

A small window opens showing the Comfy Labs logo and the first-run wizard.

Step 3 – Run the first-run wizard

The wizard is six short steps. Each step is described in detail below in First-Run Setup Wizard, but the speedrun is:

It is safe to walk away during step 5. The progress log streams every command. If anything fails, the wizard surfaces the actual error (no silent fallback) and gives you a Stop install button to clean up the partial install before retrying.

Step 4 – Pick and download your first workflows

After the runtime install finishes, the main window shows the Welcome screen with a single big button: Open Workflows. Click it.

The app opens the Settings page (a Streamlit page hosted inside the app window). Here you’ll see all 9 workflows as cards, each with:

• Name + thumbnail + short description
• VRAM badge (greyed out if your GPU is below the workflow’s minimum)
• Download size badge
• A status badge: Ready / Models missing / Unavailable (GPU)
• An action button: Install / Download models / Manage

Pick the workflows you want and click Download models on each. You don’t need all 9 – start with one or two. Each workflow downloads its model weights into your models folder; sizes range from 0 GB (PBR Tileable, all CPU) to 24 GB (Extend Image).

When the model download finishes, the page shows a Restart now / Later dialog – click Restart now so the workflow’s model paths register cleanly with ComfyUI.

Step 5 – Run your first workflow

After the restart:

1. Click Open Workflows again from the welcome screen.
2. The sidebar inside the Streamlit pane lists every installed workflow. Workflows whose models aren’t downloaded yet show as (needs models) and are disabled – click them to be sent back to Settings.
3. Click a workflow name (e.g. Text to Concept Art) and follow the on-screen instructions in the workflow’s UI.
4. Generated outputs are saved to <install>/output/<workflow>/ by default. Click the Output path on the left side of the status bar at the bottom to open the output folder in Windows Explorer.

You’re up. The rest of this manual is reference – you’ll come back to specific sections when you need them.

System Requirements

Per-workflow VRAM requirements – see the Workflows Quick Reference table below for the VRAM number tied to each workflow. The lowest-cost workflow (Make PBR Tileable Textures) needs 0 GB GPU VRAM since it’s pure CPU/PIL processing; the heaviest (Extend Image and Image to 3D Mesh) want 16 GB.

Notes:

• If GPU detection fails or nvidia-smi is missing, update your driver from nvidia.com/drivers.
• Lower-VRAM cards (e.g. 10 GB RTX 3080) can run most workflows but may spill into Windows shared GPU memory, which is much slower than dedicated VRAM. See Troubleshooting for tuning timeouts.
• The disk numbers above are the minimum-after-install. Comfy Labs’s runtime is ~21 GB on the install drive; model weights live separately on whichever drive you point at in step 3 of the wizard.
• Comfy Labs is “fully local” – no telemetry, no required accounts, no phone-home. Once installed, it works offline. The only network call after install is the optional update check (which can be triggered manually).

First-Run Setup Wizard

The wizard runs automatically the first time you launch Comfy Labs.exe. It also re-runs in Reconfigure mode if your saved configuration becomes invalid (drive unmounted, install folder deleted, etc.) – in that case a yellow banner explains what needs fixing.

Step 1 – Welcome and hardware audit

The wizard inspects your machine using nvidia-smi and Windows system info, then displays:

• GPU name and compute capability (e.g. NVIDIA GeForce RTX 4090, sm_89)
• VRAM (must be at least 4 GB)
• System RAM (must be at least 8 GB)
• Free disk on your largest drive with 25+ GB free (the wizard prefers a non-C: drive when one qualifies, but C: is allowed)
• OS version and driver version (informational)

Each row shows green if it passes the floor and red if it doesn’t. You cannot advance past this step if the audit fails the floor. If your GPU isn’t detected, install or update the NVIDIA driver and relaunch.

Step 2 – Install location

Comfy Labs needs to install ~21 GB of Python runtime, ComfyUI source, and 26 pinned custom nodes. You pick where it goes.

• The wizard suggests the largest non-C: NTFS drive with at least 25 GB free, when one qualifies. A drive other than C: is recommended (the install is heavy and most users have more headroom on a secondary drive), but C: works if you have 25+ GB free there. Single-drive setups are fully supported.
• You can browse to any folder on any drive. The validator only checks for a valid drive-letter path with enough free space; the v0.2.19-and-earlier hard block on C: is gone.
• Whatever folder you pick, the wizard appends \Comfy-Labs automatically (unless your folder is already named Comfy-Labs). This makes uninstall safe-by-construction: a Remove-Item -Recurse <install>\Comfy-Labs can never wipe out unrelated files in the parent folder.

The display below the path field shows the actual final install path so you can confirm before clicking Next.

Step 3 – Models folder

Model weights are heavy (Concept Magic alone is ~18 GB; Extend Image ~24 GB; Image to 3D Mesh ~9 GB). They live in a separate folder so you can put them on an external drive or a different internal drive from the runtime.

• Default: <install>/models/
• Recommended: an external SSD or a non-system drive with 100+ GB headroom if you plan to install most workflows.
• You can change this later in Preferences (and the next launch will use the new location).

Step 4 – Already have ComfyUI models?

If you already run ComfyUI on this PC – standalone, ComfyUI-Easy-Install, or any other distribution – the wizard can scan its models/ folder and link any matching files (by filename + size) into your Comfy Labs models folder. This can save tens of GB.

• Browse to your existing ComfyUI models folder (e.g. D:\ComfyUI-Easy-Install\ComfyUI\models), or
• Click I don’t have any – skip this step to download everything fresh.

Linking uses Windows hardlinks (cross-volume falls back to file copy automatically). Hardlinks don’t require admin rights or Developer Mode. The original files in your ComfyUI install are not modified, and uninstalling Comfy Labs will not delete them – a .comfy_labs_manifest.json records which files were linked from where.

Step 5 – Install the Python runtime

Click Start install. Behind the scenes the wizard runs python-bootstrap/bootstrap.py, which:

1. Extracts the bundled Python 3.12 runtime (extract-python) – ~5 seconds. The portable ZIP carries a relocatable CPython 3.12.13 build from astral-sh/python-build-standalone (~46 MB packed). It is unpacked into <install>/python-runtime/ and never touches PATH or the system Python.
2. Extracts the bundled MinGit (~40 MB packed) into <install>/git-runtime/ so the clone steps below work even on machines without git on PATH.
3. Detects the GPU (detect-gpu) – runs nvidia-smi, parses compute capability and VRAM.
4. Creates a Python venv (create-venv) at <install>/runtime/, built on top of the bundled interpreter.
5. Installs PyTorch + CUDA 12.8 (install-pytorch) – ~2 GB.
6. Installs FlashAttention (install-flashattn) – prebuilt wheel from the catalog mirror. If a matching wheel for your Python ABI is not yet hosted, this step is treated as a non-fatal skip; workflows still run, just without FA’s speedup.
7. Clones ComfyUI (clone-comfyui) at the pinned commit, using the bundled git binary.
8. Installs ComfyUI’s own dependencies (install-comfyui-deps).
9. Installs 26 pinned custom nodes (install-custom-nodes) – the same set the workflows depend on. If one node fails to build (broken sdist, missing C compiler, etc.), it is skipped with a clear reason and the rest of the nodes install normally; the failure is summarized in the final report.
10. Installs the Comfy Labs Streamlit app deps (install-app-deps).
11. Pins ML libraries (install-pinned-ml-deps) – diffusers, peft, huggingface_hub, transformers at the exact versions the 9 workflows require.

Each step shows in the live log pane; line color signals progress / skip / error. Total time on a typical connection: 25–45 minutes. Most of it is pip install downloading and unpacking wheels.

If a step takes a long time without printing anything (large quiet wheel downloads can sit silent for many minutes), the wizard emits a once-per-minute “still working (silent …)” heartbeat so you can tell the install is alive. Heartbeats never kill the install; the Stop install button is the only thing that kills a running bootstrap.

Two safety mechanisms:

• Stop install – the Back button becomes a red Stop install while bootstrap is running. Click it to kill the python/pip/git process tree and remove the partial install.
• Skip if already installed – if you re-run the wizard (Reconfigure mode) and the venv at <install>/runtime/pyvenv.cfg already exists, this step is auto-marked done and you can click Next immediately. Saves 25–45 minutes when only paths needed fixing.

Pip wheel cache: every wheel pip downloads during install-pytorch, install-app-deps, etc. is also written to %LOCALAPPDATA%\Comfy Labs\pip-cache\. If you ever have to retry the install (e.g. after a network drop), pip pulls from the local cache and the same step finishes in seconds instead of redownloading 3-4 GB. The cache is never wiped automatically; see Preferences for the manual wipe button and the Uninstall checklist for the standalone uninstaller’s matching item.

Step 6 – Launch Comfy Labs

When the install succeeds, click Launch Comfy Labs. The wizard saves your choices to %APPDATA%\Comfy Labs\config.json and dismisses, dropping you into the Welcome screen.

The next time you launch Comfy Labs.exe, the wizard does not re-run – you go straight to the Welcome screen.

The App Interface

After the wizard finishes, every launch of Comfy Labs lands on the Welcome screen inside a single Electron window. The window has three persistent regions:

1. Toolbar (top) – Updates, Support Log, Start/Stop ComfyUI, Output, Prefs, Help.
2. Main area (center) – Welcome screen, or the Streamlit-hosted workflow UI when you click Open Workflows.
3. Status bar (bottom) – output folder shortcut, three subprocess status dots, workflow-update badge (when updates are available), View Log, version.

Welcome screen

The welcome screen is what you see when you launch the app and any time you click Home in the toolbar.

• Comfy Labs logo and version badge.
• Open Workflows – big blue button. Disabled until Streamlit’s status dot turns green (~3–5 seconds after launch). Hovering the disabled button shows the reason. Click swaps the label to Opening Workflows… with a spinner while the BrowserView is attaching, so a slow attach doesn’t read as “did my click register?”; rapid double-clicks are guarded so only one open is ever in-flight.
• Uninstall Comfy Labs – outlined red button at the bottom (see Uninstall).

Toolbar (top)

Status bar (bottom)

Subprocess crash pane

If any of the three subprocesses dies unexpectedly, a native crash pane overlays the window with:

• The subprocess name (Streamlit / Concept Magic bridge / ComfyUI)
• Captured stderr verbatim
• Exit code
• Copy details – one-click copy to clipboard
• Send Error Report – bundles a ZIP to your Desktop (same as Support Log, but auto-tagged with the crash context)
• Restart – relaunches just that subprocess
• Dismiss – hides the pane (the subprocess stays down until you click Restart)

The crash pane is rendered by Electron itself, so it works even when Streamlit is the dead process.

Log Viewer

Click View Log in the status bar. The viewer shows app.log – a single file that contains:

• Electron main-process logs ([INFO] [App] ..., [ERROR] [Updater] ...)
• React renderer logs (forwarded via IPC)
• All three subprocesses’ stdout and stderr, line-by-line, prefixed with [PY-streamlit], [PY-cmBridge], [PY-comfyui] (errors get an extra ERR tag)

Buttons: Refresh, Copy (to clipboard), Delete log, Close. Auto-refresh streams every second by default.

The log file lives at %APPDATA%\Comfy Labs\app.log in packaged builds, or at <repo>/public/debug_logs/app.log in dev (npm start).

Preferences

Open with the Prefs toolbar button.

• Output folder – where generated images, PBR maps, 3D meshes, and ZIPs are written. Per-workflow subfolders are created automatically (<output>/text-to-concept-art/, etc.). Defaults to <install>/output/. Browse to change.

• Output retention – how long to keep generated files before sweeping them to the Recycle Bin (recoverable):

  • Never – keep everything forever
  • 24 hours (default) – matches the Streamlit-side cleanup
  • 7 days
  • 30 days

  The sweep runs at every app launch and once every 24 hours for long-running sessions. Files go to the Recycle Bin, not deleted outright – you can recover anything for as long as Windows keeps the recycle bin entries.

• Enable Concept Magic bridge – checkbox, default OFF. When checked, Comfy Labs spawns the FastAPI bridge on port 8000 so the Concept Magic Blender add-on can drive ComfyUI. When unchecked, the bridge stays unspawned (zero CPU, zero VRAM). Toggling here spawns or stops the bridge live – no restart needed.

• Pip wheel cache – shows the current cache size and a Wipe wheel cache now (~X GB) button. The cache lives at %LOCALAPPDATA%\Comfy Labs\pip-cache\ and stores downloaded Python wheels (PyTorch, transformers, etc.) so a re-install or partial-install retry doesn’t have to redownload the same ~4 GB. The cache is never wiped automatically – click the button when you want the space back. The button is disabled when the cache is already empty, and reports the freed bytes inline after a successful wipe. The cache is intentionally separate from the user’s global %LOCALAPPDATA%\pip\Cache\, so wiping it here cannot touch wheels owned by other Python installs on the machine. You can also remove this cache from the standalone uninstaller (item 7 in the Uninstall checklist).

Click Save to apply. The settings are written to %APPDATA%\Comfy Labs\config.json. The Pip wheel cache wipe runs immediately when clicked – it does not wait for Save.

Update banner

When the app detects a newer version on the update server, a thin blue banner appears below the toolbar:

Comfy Labs vX.Y.Z is available (you have vA.B.C) [Release notes] [Download] [×]

• Release notes opens the release notes URL in your default browser.
• Download opens the ZIP download URL in your default browser. Comfy Labs is portable – unzip the new version into a new folder next to the old one and launch its Comfy Labs.exe. Your config (in %APPDATA%) carries over automatically because it lives outside the app folder. Full procedure in UPGRADING_COMFY-LABS.md.
• × dismisses the banner for this session.

The check runs automatically 30 seconds after launch, and on demand when you click Updates in the toolbar. Comfy Labs will never download or install an update without your action – “Download” just opens the URL in your browser.

For the deeper end-to-end view of how the channel works (mirror layout, semver compare, what version.json looks like), see the Updates reference section below.

Workflows

Quick reference

How workflows are installed and run

Workflows are catalog-driven and installed on demand. The app ships with the workflow code (manifests + Streamlit UI) bundled, but the model weights are not included in the .zip – they’re downloaded from the catalog mirror the first time you install each workflow. This keeps the app download small (~80 MB) while giving you fine control over which 5–70 GB of model weights actually land on disk.

The Settings page (the first thing you land on after first-run setup) is where you install, update, and manage workflows. The sidebar nav and per-workflow descriptions are built dynamically from the catalog, so brand-new workflows appear there as soon as they’re installed – no app update required. Workflows declare their own nav position via display_order and category in their manifest, so the order you see is author-curated, not alphabetical.

Each workflow card shows:

• Hardware compatibility badge – greyed out + explanation if your GPU doesn’t meet the workflow’s gpu_min_sm or vram_gb minimums.
• Status badge – Ready (code + models present), Models missing (code present, weights not downloaded yet), Unavailable (GPU).
• Action button – Install / Download models / Update / Uninstall / Manage.
• Download size for new install or update.

Updates are incremental. Each workflow’s manifest.yaml carries a files: block listing every shippable file with its sha256 + size. When you click Update, the client fetches the new manifest, diffs the hashes against what you already have on disk, and downloads only the differing or missing files. Editing one node in workflow.json upstream means you download that one file, not the whole workflow folder. Sha mismatches hard-fail the install (no silent fallback), so local corruption is detected and repaired on the next try.

LoRAs update without a workflow republish. A workflow’s lora_pack model entry binds to an index.json on the mirror, so adding or replacing a LoRA upstream is a pure content publish – the change reaches you the next time you click Update on the workflow, without any app or workflow version bump.

After install or update, Comfy Labs shows a restart-required dialog (“Workflow installed / updated – Restart now / Later”). The model paths register cleanly with ComfyUI on the next launch; Restart now is the right answer unless you have a reason to defer.

You can also Import Workflow from the Settings page top bar – accepts a .zip matching the manifest folder structure (manifest.yaml + ui.py + workflow.json) or a local folder with the same structure. Manual imports show an “unsigned source” warning every time, because importing runs arbitrary ui.py Python code.

Imported workflows install to %APPDATA%\Comfy Labs\workflows\<id>\ and survive .zip updates of the app itself.

General requirements

• GPU + VRAM: see the System Requirements section above and the per-workflow VRAM column in the Quick Reference table.
• ComfyUI: must be running for AI-powered features. Status shown in the status bar at the bottom of the app window. ComfyUI is lazy-spawned – the dot is gray until the first workflow run, then yellow (starting), then green.
• Supported image formats (all workflows): PNG, JPG, JPEG, WEBP.

Getting help inside a workflow

If a generation fails:

1. Check the ComfyUI status dot in the status bar – gray means it’s stopped, red means it crashed.
2. Click View Log in the status bar for error details.
3. Refresh the workflow page (Ctrl+R inside the Streamlit area, or click Home -> Open Workflows).
4. If a generation hangs, click Stop ComfyUI in the toolbar to free VRAM and cancel the run, then click Start ComfyUI to relaunch the backend.
5. If the GPU is wedged (rare), reset the Windows display driver with Win+Ctrl+Shift+B.

Workflows timing out on a slow GPU

If any workflow fails with a ⏱ timeout message, see Troubleshooting for tuning COMFY_LABS_TIMEOUT_MULTIPLIER.

1. Extend Image

Extend any image beyond its borders using AI. Upload an image, choose how much to expand, and the AI generates seamless background extensions that match the original content.

1.1 Getting started

1. Open Comfy Labs and click Open Workflows on the welcome screen.
2. Click Extend Image in the sidebar.
3. ComfyUI will lazy-spawn on the first generation; the status dot in the bottom status bar goes yellow (starting) then green (running).

1.2 Upload image

Upload any image you want to extend.

• Any size and aspect ratio
• The source image dimensions are shown below the preview

1.3 Expansion mode

Choose how the image should be expanded:

Percentage

Expand each side by a fixed percentage of the original dimensions.

• Options: 10%, 15%, 20%, 25%, 30%, 40%, 50%
• Default: 25%
• The output dimensions are shown below the slider

Aspect ratio

Expand the image to fit a target aspect ratio. The AI fills in whichever sides need padding.

• Options: 1:1 (Square), 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
• If the image already matches the selected ratio, no expansion is needed

1.4 Prompt options

Control what the AI generates in the extended area:

No prompt (default)

Works best for most images. The AI infers what to generate from the existing content.

Anti-hallucination

Prevents text, UI elements, labels, and watermark artifacts. Use this when extending viewport renders or screenshots.

Auto-describe

Uses AI to caption the image first, then uses that description to guide the extension.

1. Click Generate description to auto-caption the image
2. Edit the description in the text area if needed
3. The description guides the AI’s fill – useful for complex scenes

1.5 Seed control

• Seed – controls randomness. Same seed = same result.
• Lock checkbox – keeps the seed fixed between runs. When unlocked, a new random seed is used each time.

1.6 Generate and download

1. Click Outpaint to start generation.
2. A spinner shows progress while the AI works.
3. The result appears below with dimensions shown.
4. Click Download PNG to save.

To try a different result, adjust the seed (or leave it unlocked) and click Outpaint again.

1.7 Tips for best results

• No prompt works best for most images – the AI naturally extends the content.
• Use Anti-hallucination for viewport renders, UI screenshots, or images with text near the edges.
• 25% expansion is a good starting point – larger expansions give the AI more creative freedom but may diverge from the original.
• Aspect ratio mode is ideal when you need a specific format (e.g., converting a square image to 16:9 for a banner).

1.8 Troubleshooting

Extended area doesn’t match the original style

Try a different seed. The AI generates different results each time. You can also try Auto-describe to give the AI more context about the image content.

Visible seam between original and extended area

This is rare with the current pipeline. If it happens, try a slightly different expansion percentage or a new seed.

Generation fails

• Check the ComfyUI status dot in the status bar.
• Click View Log for error messages.
• Try a smaller expansion percentage.

2. Make PBR Tileable Textures

Create seamless, tileable PBR texture sets from any photo or text prompt. This workflow converts a single image into a complete material set: tileable diffuse, normal map, roughness map, and height map – ready to drop into Blender, Unreal, Unity, or any 3D application.

Requirements:

• ComfyUI must be running for AI-powered features: Generate from Prompt, Zoom Out 2x, and PBR map generation.
• The basic tiling algorithm (Moisan + TexTile) works without ComfyUI.

2.1 Step 1: Choose your source

At the top you’ll see two options:

Option A: Upload Image

Upload any texture photo – a phone photo of wood, a scan of fabric, a downloaded texture, etc.

• Any size and aspect ratio (will be cropped/resized as needed)
• Best results with flat, evenly-lit surfaces

Option B: Generate from Prompt

Create a texture from scratch using AI.

1. Describe your texture – e.g., “weathered red brick wall”, “dark walnut wood planks”, “rough concrete with cracks”.
2. Variations – generate 1 to 4 different versions (default: 1).
3. Seed – controls randomness. Same seed = same result. Each variation auto-increments the seed by 1.
4. Click one of:
   • Generate 1K – standard 1024x1024 output (faster).
   • Generate 2K (for cropping) – 2048x2048 output, useful when you want to crop to the best region.
5. Toggle “Show mirror preview” to see how each variation looks when tiled.
6. Click Select on the variation you like best.
7. Click Download on any variation to save it.

After selecting, you can click Back to generation to try different prompts or seeds.

2.2 Step 2: Pre-processing

Choose how to prepare the image before tiling:

None

Uses the image as-is. Best when your source is already well-framed and roughly square.

Crop

Interactively select a square region of the image.

1. Drag the red handles to frame the area you want.
2. The crop is locked to a 1:1 (square) aspect ratio.
3. A warning appears if your crop is smaller than 512px (may produce low-quality results).
4. Click Apply Crop to preview the result.
5. Click Re-crop to adjust if needed.

Outpaint (Zoom Out 2x)

Expands the image by generating new texture around the borders. This gives the tiling algorithm more material to work with, reducing visible repetition in the final tile.

1. If your image isn’t square, you’ll see a resized preview (center-cropped to 1024x1024). Click Continue to proceed.
2. Click Zoom Out 2x – the AI mirror-pads your texture to double size, then re-generates it at the original resolution.
3. Match original contrast slider (default: 100%) – the zoom-out process can reduce contrast. This slider transfers the color statistics from your original image to restore the look. Drag to 0% to see the raw result.
4. Compare the Original (left) and Zoom Out 2x (right) side by side.
5. Click Use This to proceed, or Regenerate for a different result.

2.3 Step 3: Make tileable

Configure the tiling process:

Output size

• 1024 – standard resolution, faster (~7 seconds).
• 2048 – high resolution, takes longer.

Remove lighting gradient (optional)

Enable this if your photo has uneven lighting. The slider controls intensity:

• 20 – gentle correction
• 60 – moderate (recommended starting point)
• 100 – most aggressive

Sharpen texture (optional)

Applies an unsharp mask to restore crispness. Useful after zoom-out or if the source is slightly soft.

Run

Click Make Tileable to process. A progress bar shows the current step and live TexTile score.

Results

• TexTile Score – measures how seamlessly the texture tiles (0 to 1). Professional textures score 0.85+.
• Tileable texture (left) – your final seamless texture.
• 3x3 tile preview (right) – shows 9 copies tiled together so you can visually check for seams or repetition.
• Download Tileable PNG and Download 3x3 Preview buttons.

2.4 Step 4: Generate PBR maps

Click Generate PBR Maps to create material maps from your tileable texture. This requires ComfyUI to be running.

Each map has its own Download button.

2.5 Step 5: Adjust maps

Expand the Adjust Maps section to fine-tune any map (including the diffuse).

Each map has its own tab with these controls:

• Histogram – shows the current intensity distribution. Updates live.
• Input Levels – two-handle slider (black point / white point). Drag to stretch contrast.
• Gamma – < 1.0 darkens midtones; 1.0 = no change; > 1.0 brightens.
• Output Levels – remaps the output range. Useful for clamping (e.g., 0.1, 0.9).
• Hue Shift (Diffuse only) – rotate the color wheel 0–360 degrees.
• Saturation (Diffuse only) – 0% (grayscale) to 200% (oversaturated).
• Reset – restore a map to its original values.

2.6 Step 6: Download

Individual downloads

Every image displayed throughout the workflow has a Download button.

Download All (ZIP)

After generating PBR maps, a Download All (ZIP) button packages:

• Tileable diffuse texture
• 3x3 tile preview
• Normal map
• Roughness map
• Height map

If you adjusted any maps, the ZIP includes the adjusted versions.

2.7 Tips for best results

Choosing good source images

• Flat, top-down photos work best – avoid perspective or heavy shadows.
• Even lighting is critical – uneven lighting creates visible gradients when tiled. Use the “Remove lighting gradient” option if needed.
• Larger source = better quality – start with the highest resolution you have.

Reducing visible repetition

The tiling algorithm makes edges seamless, but distinctive features (knots in wood, unique cracks) will repeat visibly. To minimize this:

• Use Zoom Out 2x to give the algorithm more material with more variety.
• Generate at 2K and crop to select the most uniform region.
• Avoid sources with large unique features – textures with small, repeating patterns (fine grain, small tiles, pebbles) tile best.

Prompt tips for Generate from Prompt

• Be specific: “light oak wood planks, fine grain” beats “wood”.
• Include “seamless” or “tileable” in your prompt for better results.
• Add “top down view, flat even lighting” (auto-added, but reinforcing helps).
• Generate 4 variations and pick the most uniform one.

2.8 Using in Blender

Import the texture set

1. Open your Blender project.
2. In the Shader Editor, create a new Principled BSDF material.
3. Add Image Texture nodes for each map:

Set up tiling

1. Add a Texture Coordinate node -> Mapping node before your Image Textures.
2. Connect UV output from Texture Coordinate to Mapping input.
3. Adjust Scale in the Mapping node (e.g., Scale X=2, Y=2 for 2x tiling).

Displacement setup (optional)

1. Material Properties -> Settings -> Surface, set Displacement to “Displacement and Bump” or “Displacement Only”.
2. Add a Displacement node between the height map and Material Output’s Displacement input.
3. Adjust the Scale value (start with 0.01–0.05).
4. Add a Subdivision Surface modifier so geometry has resolution to displace.

2.9 Troubleshooting

“ComfyUI: Offline” – the dot in the status bar is gray

ComfyUI lazy-spawns on the first AI request – click Generate from Prompt, Zoom Out 2x, or Generate PBR Maps and it will start automatically (~10–30 s). The basic tiling algorithm works without ComfyUI.

PBR generation fails or shows no maps

• Check the ComfyUI status dot is green.
• Click Stop ComfyUI in the toolbar (confirm), wait for the dot to go gray, then click Start ComfyUI to bring it back.
• Click View Log for error messages.

Tiling looks good but PBR maps look flat

The PBR model works best with textures that have visible surface detail. Use the Adjust Maps controls to boost contrast on the normal or height maps.

Zoom Out 2x result is washed out

Use the Match original contrast slider (default 100%) to restore the color/contrast from your original. If it’s still not right, try Regenerate.

App freezes during generation

1. Click View Log to see what’s stuck.
2. Click Stop ComfyUI in the toolbar (confirm), wait for the dot to go gray, then click Start ComfyUI to bring it back. If ComfyUI looks orphaned even after Comfy Labs quits, use Force-Quit-ComfyUI.bat next to Comfy Labs.exe.
3. If the GPU itself is wedged (rare), press Win+Ctrl+Shift+B to reset the display driver.

3. Remove Background

Remove the background from any image with one click. Get a transparent PNG and a black/white mask – ready for compositing, 3D modeling, or use in other workflows.

3.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Remove Background in the sidebar.

3.2 Upload image

Upload any image with a subject you want to isolate.

• Any size and aspect ratio.

3.3 Remove background

1. After uploading, a preview of your source image appears.
2. Click Remove Background.
3. A spinner shows progress while the AI processes the image.

3.4 Results

Two outputs are displayed side by side:

Click Download PNG to save the transparent result.

3.5 Tips for best results

• Clear subjects work best – objects, people, animals with distinct edges.
• Busy backgrounds are handled well, but very similar foreground/background colors may produce rough edges.
• Use this before Image to 3D Mesh – the mesh generator works best with objects on a plain or transparent background.

3.6 Troubleshooting

Edges are rough or jagged

The AI model handles most cases well. If edges are rough, try an image with higher contrast between the subject and background.

Part of the subject is removed

This can happen with thin or transparent elements (glass, wire, hair). The AI prioritizes the main subject mass.

Background removal fails

• Check the ComfyUI status dot.
• Click View Log for error messages.
• Click Stop ComfyUI in the toolbar (confirm), then Start ComfyUI once the dot goes gray.

4. Image to 3D Mesh

Generate a textured 3D mesh from a single image. Upload a photo of an object and get a downloadable GLB file with UV-mapped textures – ready to import into Blender, Unity, Unreal, or any 3D application.

4.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Image to 3D Mesh in the sidebar.

GPU note: Trellis2 (the underlying model) is fully validated on RTX 50-series; 30/40-series can run smaller meshes but may hit VRAM ceilings on complex geometry.

4.2 Upload image

Upload an image of the object you want to convert to 3D.

• Any size (will be processed internally).
• Best with: objects on a plain or transparent background.

4.3 Options

Seed

Same seed = same mesh. Change the seed to get a different interpretation.

Remove background before processing

Enable this if your image has a busy background. The AI removes the background first, which dramatically improves mesh quality.

• Off (default): Use when your object is already on a plain/white/transparent background.
• On: Use when the background is complex.

4.4 Generate

1. Click Generate 3D Mesh.
2. A progress bar tracks the generation pipeline.
3. Total wall time is typically 5–20 minutes depending on the input image and your hardware. The pipeline runs in two distinct phases:
   • GPU phase (~30–90 seconds): Trellis2 sparse-structure sampling, low-res / high-res SLat, texture SLat, BVH build, and dual contouring all run on the GPU. You’ll see VRAM utilization spike here.
   • CPU phase (~5–15 minutes): mesh post-processing, then UV unwrapping via xatlas. xatlas is a single-threaded CPU library – there is no GPU path for it – so during this phase nvidia-smi will show the GPU idle and one CPU core pinned at 100%. This is normal, not a hang. The Streamlit progress text updates with elapsed time every few seconds; if the elapsed counter is still incrementing, the unwrap is still working.
   • Final GPU phase (~10–30 seconds): texture bake jumps back to the GPU.

Dense / complex meshes spend longer in the xatlas phase because chart computation is superlinear in face count. A simple object (~500k faces post-simplification) finishes in ~5 min; a clown-car-shaped or highly detailed object (~2M faces) can take 10–15 min on UV unwrap alone.

4.5 3D viewer

After generation, an interactive 3D viewer appears in-browser:

• Click and drag to rotate.
• Scroll to zoom.
• Auto-rotate is enabled by default.
• Lighting and shadows are applied.

The file path to the generated GLB is shown above the viewer.

4.6 Download

Click Download GLB to save the mesh. GLB includes:

• 3D geometry (mesh)
• UV-mapped textures
• Material data

GLB is widely supported by 3D applications, game engines, and web viewers.

4.7 Tips for best results

Input image quality

• Single object photos work best.
• Plain background (white, transparent) gives the cleanest results.
• Front-facing view with the full object visible produces the most complete mesh.
• Even lighting helps the model understand surface detail.

When to use Remove Background

Object types that work well

• Props, furniture, vehicles, characters
• Hard-surface objects with clear geometry
• Objects with distinct silhouettes

Object types that are challenging

• Very thin/flat objects (cards, paper)
• Highly reflective/transparent objects (glass, mirrors)
• Objects with complex internal structure

4.8 Using in Blender

1. File -> Import -> glTF 2.0 (.glb/.gltf).
2. Select the downloaded GLB file.
3. The mesh imports with its UV-mapped texture already applied.
4. You may need to adjust the scale.

Post-import cleanup

• Check the mesh topology – AI-generated meshes may need retopology for production use.
• The texture is baked into the material – you can re-UV and re-texture if needed.

4.9 Troubleshooting

Mesh is missing parts or looks incomplete

• Try a different angle that shows more of the object.
• Enable Remove background before processing.
• Try a different seed.

Mesh has no texture / appears gray

Click View Log for errors. The texture generation may have failed while the geometry succeeded.

Generation fails completely

• Check the ComfyUI status dot.
• Ensure Trellis2 models are installed (Settings page -> Image to 3D Mesh -> Ready).
• Click View Log for error messages.

3D viewer doesn’t load

The viewer requires JavaScript. Some browser extensions (ad blockers) may interfere with the model-viewer component (the Streamlit pane uses Chromium internally).

5. Text to Concept Art

Generate concept art from a text prompt. Creates images on a white background and optionally removes the background, outputting transparent PNGs ready for 3D modeling reference or compositing.

5.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Text to Concept Art in the sidebar.

5.2 Describe your concept

Enter a description in the text field.

Examples:

• “a cute cartoon dwarf warrior holding an axe and shield”
• “futuristic hover bike, side view”
• “medieval stone tower with ivy”

5.3 Fix and edit prompt

1. Click Fix Prompt – this appends “, create a full color 3d model on white background” to your description.
2. An editable text area appears with the full prompt.
3. Modify if needed.

5.4 Generation settings

Variations

1, 2, or 4 (default: 4). Each uses a different seed.

Seed

• 0 (default): Random seed.
• Any other number: Fixed base seed; each variation auto-increments from it.

Generate

Click Generate to start.

5.5 Select and refine

After generation, all variations are displayed in a grid.

1. Click Select on the variation you like best.
2. The selected image is shown larger with two options:

Remove Background

Click Remove Background to automatically isolate the subject and create a transparent PNG.

Download PNG

Download the selected image (with or without background removal applied).

Back to results

Returns to the grid to pick a different variation.

5.6 Tips for best results

Prompt tips

• Be specific about the object: “medieval iron warhammer with leather grip” beats “hammer”.
• Specify the view: “front view”, “side view”, “3/4 angle”.
• Include style cues: “cartoon”, “realistic”, “stylized”, “low poly”.
• The auto-appended text works well for most concepts – leave it unless you have a specific reason to change it.

Choosing from variations

• Generate 4 variations for the best selection.
• Look for clean edges, good proportions, and the level of detail you need.
• If none are good, try rephrasing the prompt or changing the seed.

5.7 Troubleshooting

Generated images don’t match the description

• Add more detail to your prompt.
• Try different seeds (set seed to 0 for random).
• Make sure the “Fix Prompt” text wasn’t accidentally deleted.

Background removal cuts off part of the object

This can happen with thin elements that blend into the white background. Try a prompt that produces the object with more contrast against white.

Generation fails

• Check the ComfyUI status dot.
• Click View Log for error messages.

6. Concept Magic

Turn 3D blockouts, sketches, depth maps, or photos into photorealistic styled images. Upload any image, choose edge or depth control, enter a prompt, and the AI generates a styled result that follows the structure of your input.

6.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Concept Magic in the sidebar.

6.2 Upload image

Upload the image you want to transform. This can be:

• 3D blockout / graybox render – rough 3D geometry from Blender, Maya, etc.
• Sketch or line drawing
• Depth map
• Photo – any existing image you want to restyle.

6.3 Prompt

Describe the desired output.

Examples:

• “futuristic Blade Runner city at night, neon lights, wet streets, rain, volumetric fog, cinematic, photoreal”
• “cozy medieval tavern interior, warm candlelight, wooden beams”
• “sleek sports car in a showroom, studio lighting, photorealistic”

The prompt controls style, mood, and content – the input image controls structure and composition.

6.4 Generation settings

Variations

1, 2, or 4.

• 1 variation: You choose the control type (Canny or Depth).
• 2 or 4 variations: Automatically split 50/50 between Canny and Depth.

Control type (1 variation only)

Output resolution

• 512x512, 768x768, 1024x1024 (default)
• 512x904 (portrait), 904x512 (landscape)

Seed

• 0 (default): Random seed.
• Any other number: Fixed seed.

6.5 Generate and results

1. Click Generate.
2. A progress bar shows generation progress for each variation.
3. Results appear in a grid below.

Each result shows the generated image, the control type used, the seed, and a Download button.

6.6 Tips for best results

Input image tips

• 3D blockouts produce the best results.
• Simple compositions work better than complex cluttered scenes.
• Consistent lighting helps coherent output.
• Higher contrast gives stronger structural guidance.

Canny vs Depth

• Use Canny for hard-surface design (architecture, mechanical).
• Use Depth for organic forms and environments.
• Generate 2 or 4 to compare both.

Prompt tips

• Focus on style and mood – structure comes from your image.
• Include lighting descriptions: “golden hour”, “neon lights”, “studio lighting”.
• Include material descriptions: “stone”, “metal”, “wood”, “glass”.
• Add “photorealistic” or “cinematic” for realism.

6.7 Troubleshooting

Output ignores the input structure

• The input image may not have enough contrast or clear structure.
• Try Canny for clear lines, Depth for clear spatial layout.

Output looks blurry or low quality

• Use 1024x1024 resolution.
• Add quality descriptors: “highly detailed”, “sharp”, “8K”.

Generation fails

• Check the ComfyUI status dot.
• Click View Log for error messages.

7. Concept Magic LoRA

Concept Magic with custom style support. Upload an image, pick a trained LoRA style, enter a prompt, and generate edge-guided results in that style.

7.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Concept Magic LoRA in the sidebar.
3. LoRAs are downloaded automatically when you install this workflow on the Settings page.

7.2 Upload image

Upload the image you want to transform (3D blockout, sketch, depth map, or photo).

7.3 LoRA style

Select a trained LoRA style from the LoRA style dropdown. Available styles are scanned from the LoRA directory at startup. Four styles ship by default:

• industrial-design1 – industrial/product design aesthetic
• scifi-outside-env – sci-fi exterior environments
• scifi-product-design – sci-fi product/vehicle design
• syd-mead – Syd Mead-inspired futuristic concept art

The trigger word for the selected LoRA is displayed below the selection. This word is automatically prepended to your prompt.

7.4 Prompt

Describe the desired output. The LoRA’s trigger word is auto-prepended – you don’t need to include it.

Example: trigger sydmead_style + your prompt “futuristic city street” = “sydmead_style, futuristic city street”.

7.5 Generation settings

Variations

1, 2, or 4.

Control type

• Canny – hard edges. Best for mechanical/architectural subjects.
• Depth – depth estimation. Best for organic shapes and depth-varied scenes.

Output resolution

• 512x512, 768x768, 1024x1024 (default)
• 512x904 (portrait), 904x512 (landscape)
• 1280x720, 720x1280 (widescreen)

LoRA strength

• 0.0 – no LoRA effect
• 1.0 – standard
• 1.75 (default) – stronger
• 3.0 – maximum (may over-stylize)

Seed

• 0 (default): Random.
• Any other number: Fixed.

7.6 Bypass options

7.7 Generate and results

1. The full prompt (with trigger word) is displayed when you click Generate.
2. A progress bar shows generation progress for each variation.
3. Results appear in a grid with the seed shown below each image.
4. Each result has a Download button.

7.8 Tips for best results

LoRA strength tuning

• Start at 1.75 and adjust.
• Too low (< 1.0): Subtle style.
• Too high (> 2.5): Over-stylized.
• Each LoRA has its own sweet spot – experiment.

Input image tips

• Simple blockouts with clear geometry work best.
• High-contrast inputs give stronger Canny guidance.

Comparing with and without LoRA

Use Bypass LoRA to generate the same prompt without the style. This shows what the LoRA contributes vs. the base model.

7.9 Troubleshooting

“No LoRAs found” error

LoRA files haven’t been downloaded yet. Open Settings, find Concept Magic LoRA, click Download models.

Style is barely visible

• Increase LoRA strength (try 2.0–2.5).
• Make sure the trigger word is present in the prompt (it’s auto-prepended).
• Some LoRAs are trained subtly – this is by design.

Output has artifacts

• Reduce LoRA strength (try 1.0–1.5).
• Try a different seed.

Generation fails

• Check the ComfyUI status dot.
• Click View Log for error messages.

8. Upscale Image

Upscale any image using AI super-resolution. Choose between fast tensor-based upscaling that stays faithful to the original, or detail-enhancing AI diffusion that adds fine detail. Scale by multiplier (1x–4x) or set a maximum dimension.

8.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Upscale Image in the sidebar.

8.2 Upload image

Upload any image you want to upscale. Any size and aspect ratio. Source dimensions are shown in the preview caption.

8.3 Upscaler

AI diffusion upscaling using SeedVR2.

• Quality: Adds fine detail and texture that wasn’t in the original.
• Best for: Most upscale jobs – photos, AI-generated art, textures, scans.
• Scale range: 1x–4x.

Note (v0.2.15+): the older “Fast (Tensor)” RTX VSR mode was dropped because its dependency (nvidia-vfx) silently downloaded a 490 MB prebuilt wheel during install with zero output, hanging fresh installs on slow connections. SeedVR2 covers the same use cases with better quality, just slower.

8.4 Resize mode

Scale by multiplier

• Slider from 1.0x to 4.0x in 0.25 steps.
• Output dimensions shown in the preview caption.
• Dimensions are rounded to multiples of 8.

Max dimension

• Enter a value from 64 to 8192.
• Aspect ratio preserved – only the longest edge matches the target.
• Dimensions rounded to multiples of 8.

8.5 Upscale and compare

1. Click Upscale.
2. A spinner shows progress.

After completion, two views are displayed:

Detail comparison slider

• Left: Original image (nearest-neighbor upscale).
• Right: AI-upscaled result.

Drag the slider to compare detail quality.

Full result

The complete upscaled image at full resolution.

8.6 Download

Click Download to save the upscaled image as PNG. The filename includes the upscaler used and output dimensions (e.g., photo_seedvr2_2048x2048.png).

8.7 Tips for best results

Scale factor tips

• 2x is the sweet spot for most use cases.
• 4x works on clean source images; for noisy or already-soft sources, do two passes at 2x to keep the detail crisp.
• Very large upscales (8x+) almost always read better as two 2x passes than a single 4x.

Image quality considerations

• Clean source images produce better results than noisy or compressed ones.
• JPEG artifacts will be amplified – use PNG sources when possible.
• Detail (AI) can hallucinate detail – verify if accuracy matters.

8.8 Troubleshooting

Upscaled image looks blurry

• The source image may be too low resolution – SeedVR2 enhances detail but can’t recover information that isn’t there.
• Try a higher-resolution crop of the same source if available.

Upscaled image has artifacts

• Try 2x instead of 4x. Larger jumps over-extrapolate from the source and can hallucinate texture that wasn’t there.
• For very low-quality sources (heavy JPEG compression, screen-grabs), the AI will amplify the existing artifacts. Use a cleaner source if possible.

Generation fails or takes very long

• Large images at high scale factors require significant VRAM.
• Try a smaller scale factor or use Max dimension mode.
• Click View Log for out-of-memory errors.
• If a “⏱ timed out” banner appears, see Troubleshooting.

9. Create Ortho Views

Generate 4 orthographic views (front, side, back, side) from a single image. Uses AI multiview generation with automatic evaluation to drop low-quality or off-angle views.

9.1 Getting started

1. Open Comfy Labs and click Open Workflows.
2. Click Create Ortho Views in the sidebar.

9.2 Upload image

Upload an image of the object you want orthographic views of.

• Any size.
• Best with: clear photos of single objects, concept art, 3D renders.

9.3 Generate

Generate Ortho Views

Click Generate Ortho Views. The AI:

1. Generates 6 multiview images from your input.
2. Evaluates each view for angle accuracy.
3. Keeps only the cardinal-direction views (0°, 90°, 180°, 270°).
4. Drops any 3/4 angle or off-axis views.

Try New Seed

Click to regenerate with a different random seed.

9.4 Results

Composite view

Expand “All 6 generated views (before evaluation)” to see the raw output.

Orthographic views

The kept views are displayed in a grid, labeled by direction (FRONT, BACK, LEFT, RIGHT).

Final sheet

A combined sheet image showing all accepted orthographic views in a single image – useful as a modeling reference sheet.

9.5 Download

Each individual view has its own Download button with a descriptive filename (e.g., ortho_robot_front.png).

The Download Sheet button saves the combined reference sheet.

9.6 Tips for best results

Input image tips

• Single, clear subject with a distinct silhouette.
• Plain or transparent background.
• Front or 3/4 view works best as input.
• Well-lit, detailed images.

What works well

• Characters and figurines
• Vehicles and props
• Hard-surface objects with clear geometry
• Objects with distinct features on all sides

What’s challenging

• Symmetrical objects
• Very flat objects (cards, screens)
• Objects with no clear “front” (spheres, abstract shapes)

Using as modeling reference

1. Download the sheet and import it as a background image in your 3D viewport.
2. Or download individual views and set them as front/side/back reference images.
3. The views are approximately orthographic – use them as guides, not exact projections.

9.7 Troubleshooting

“No orthographic views passed evaluation”

The AI’s views were all at off-angles. Click Try New Seed for a different result, or try a different input image with a clearer front-facing view.

Only 2 or 3 views generated (not 4)

The evaluation step filters aggressively – it only keeps genuinely cardinal-direction views. Some objects may not produce clean views from all 4 angles.

Views don’t look consistent

The AI generates views independently, so there may be slight inconsistencies between views. This is a known limitation of current multiview generation models.

Generation fails

• Check the ComfyUI status dot.
• Click View Log for missing-model errors.

Concept Magic Bridge (Blender add-on integration)

If you use the Concept Magic Blender add-on, Comfy Labs hosts the FastAPI HTTP service the add-on talks to. The bridge runs on http://127.0.0.1:8000 (loopback only – nothing exposed to your LAN) and exposes a versioned /v1/... API that proxies requests to the ComfyUI backend.

Enabling the bridge

The bridge is off by default so users who don’t use the Blender add-on don’t pay for an idle uvicorn process.

1. Open Prefs in the toolbar.
2. Check Enable Concept Magic bridge.
3. Click Save.

The bridge spawns immediately (status dot in the bottom bar turns yellow then green). Toggling the checkbox stops/starts the bridge live – no app restart needed.

The bridge only spawns once first-run setup is complete (first_run_complete: true in config.json). This prevents spurious crash panes when ComfyUI hasn’t been warmed up yet.

What the Blender add-on can do

• Pre-load Concept Magic models into VRAM (/v1/warmup)
• Free VRAM after a session (/v1/unload)
• Generate styled images from a Blender viewport render (/v1/generate)
• Generate with a custom LoRA (/v1/generate/lora)
• Send/receive base64-encoded images for in-process pipelines (/v1/generate/base64)
• Check the lifecycle state of all three Comfy Labs subprocesses (/v1/process-status)
• Lazy-spawn ComfyUI on demand (/v1/ensure-comfyui-running)

For the full API contract, see python/cm_bridge/CM_BRIDGE_API_v1.md in the repo.

Add-on connection states

The add-on always shows you what’s happening:

• “Comfy Labs is not running. Start it from the Start menu.” – the Comfy Labs window is closed.
• “ComfyUI is starting (~10–30 s). Please wait.” – ComfyUI is warming up.
• “ComfyUI crashed. Open Comfy Labs to restart it.” – ComfyUI exited; check the crash pane in Comfy Labs.
• “Workflow X failed: ” – per-job error returned from /v1/generate.

Spurious cm_bridge HTTP 400 errors

If you have Enable Concept Magic bridge turned on but you have not installed the Concept Magic workflow’s models, the bridge’s startup pre-load attempt will fail with a noisy validation error in the log (look for HTTP 400 lines mentioning z_image_turbo_bf16.safetensors or Z-Image-Turbo-Fun-Controlnet-Union).

Two safe fixes:

• Install the Concept Magic workflow from the Settings page (downloads the missing models).
• Or, if you don’t use Concept Magic at all, uncheck Enable Concept Magic bridge in Preferences. The bridge stays off entirely.

Updates

Comfy Labs has two independent update channels. They check different mirrors and update different things; nothing in one ever blocks the other.

App update channel (the toolbar Updates button)

Comfy Labs checks for new versions of the app shell itself automatically 30 seconds after each launch, and on demand when you click Updates in the toolbar.

The check fetches https://www.widgetgadget.com/cw1/Comfy-Labs/version.json (a tiny JSON file with version, downloadUrl, and an optional releaseNotes link), compares the published version to the running version with a numeric semver comparison, and broadcasts one of four states to the renderer:

• Update available – a thin blue banner appears below the toolbar with the new version number, Release notes and Download buttons, and a × dismiss button. Both buttons open the matching URL in your default browser.
• Up to date – a green banner appears (only when you clicked the toolbar button manually; the silent startup check does not show this).
• Offline – a yellow banner saying “Cannot reach update server.” Same caveat: only shown for manual checks.
• Dev build – gray banner; only ever shown in unpackaged dev runs.

Comfy Labs is portable – to install an update, just unzip the new version into a new folder next to your current one and launch its Comfy Labs.exe. Your config (in %APPDATA%), models folder, output folder, pip wheel cache, and installed workflows all carry over automatically because they live outside the app folder. The full procedure is in UPGRADING_COMFY-LABS.md.

The app will never download or install an app update without your action. Clicking Download just opens the URL in your browser. You stay in control of when and where the new version lands.

Workflow update channel (the StatusBar badge)

Workflows are versioned independently from the app. New LoRAs, fixed graphs, or brand-new workflows can ship without an app release.

On every launch, the Electron main process fetches catalog.json from the workflow mirror (primary https://filedn.com/lLMW4jXsJqxXkRYjd1UCoKL/comfy-labs/, with https://web.cw4.me/comfy-labs/ as a backup) and compares each workflow’s manifest_sha256 against your local manifest’s hash:

• A mismatched hash on an installed workflow = a workflow update is available.
• A catalog entry with no local manifest at all = a brand-new workflow you can install.

The combined count surfaces in the StatusBar as a clickable badge:

• “N workflow update(s) available”
• “N new workflow(s) available”
• “N updates + M new available”

Click the badge to jump straight to the Settings page. Each affected workflow card shows an Update or Install button. Workflow installs are incremental – only the files that changed get downloaded (manifest.yaml lists every shippable file with its sha256 + size, the client diffs hashes against local copies, and pulls only differing or missing files). For most workflow updates that means a few hundred KB instead of the full multi-GB workflow folder.

After a workflow install or update completes, Comfy Labs shows a restart-required dialog (“Workflow installed – Restart now / Later” or “Workflow updated …”). The model paths register cleanly with ComfyUI on the next launch, so Restart now is the right answer unless you have a reason to defer.

If the catalog mirror is unreachable on launch, the badge stays hidden and Settings falls back to your locally bundled list. No network = no nag.

Troubleshooting

Cross-cutting issues that affect more than one workflow. For workflow-specific problems, see the Troubleshooting subsection inside each workflow’s chapter.

Comfy Labs won’t launch

“Windows protected your PC” / SmartScreen warning

The build is unsigned during the closed beta. Click More info -> Run anyway.

Comfy Labs.exe opens then immediately closes

Make sure you didn’t move Comfy Labs.exe out of its folder – the sibling resources/ tree is required. If you want a shortcut elsewhere, right-click the .exe -> Pin to taskbar or Pin to Start, or run create-shortcut.ps1.

If the issue persists:

1. Open %APPDATA%\Comfy Labs\app.log in Notepad to see the last error.
2. Try unzipping the build again to a fresh folder.

“Another instance is already running”

Comfy Labs uses a single-instance lock to prevent port collisions on 8501 / 8000 / 8188. Either bring the running window to the foreground (the new launch focuses it automatically) or close it from Task Manager (Comfy Labs.exe).

Workflow timing out on a slow GPU

Every workflow has a built-in time limit (typically 2–30 minutes depending on the workflow). If processing takes longer, the operation aborts and you’ll see a ⏱ banner.

This is most common on lower-VRAM GPUs (10 GB or less) doing large outputs. When a model exceeds dedicated VRAM, Windows spills the overflow into shared system memory accessed over PCIe, which is 10–100× slower than VRAM.

First steps (no config changes)

1. Reduce the input image size, scale factor, output dimension, or batch.
2. Close other GPU-using apps (browsers with hardware acceleration, video editors, games).
3. Click View Log in the status bar – it tells you which step actually timed out.

Extending timeouts globally

Set a Windows environment variable before launching the app:

COMFY_LABS_TIMEOUT_MULTIPLIER=2.0

• Range: 0.5 to 10.0. Use 2.0 to double, 3.0 to triple. Default = 1.0.
• Applies to every workflow.
• Set it via System Properties -> Advanced -> Environment Variables, or in a batch file that launches the app.

Pinning the SeedVR2 (Detail-AI) upscaler to an exact value

Set:

SEEDVR2_TIMEOUT_S=3600

• Range: 60 to 7200 seconds.
• Affects only the Detail (AI) upscaler.
• Most users should use COMFY_LABS_TIMEOUT_MULTIPLIER instead.

A workflow fails with a generic error (likely out of VRAM)

If a workflow finishes with a vague banner like “Generation failed”, “Failed to generate variation N”, or “Upscale failed. No specific error was returned. Open View Logs to see what happened.” – and ComfyUI did not crash (its dot is still green) – the most common cause is the GPU ran out of VRAM during the run. Comfy Labs reports this generically today; the specific reason lives in the log.

Confirming it’s OOM

1. Click View Log in the status bar.
2. Scroll to the moment the workflow failed and look for any of these markers in the [PY-comfyui] / [PY-comfyui ERR] lines:
   • CUDA out of memory
   • OutOfMemoryError
   • Allocation on device 0 would exceed allowed memory
   • torch.cuda.OutOfMemoryError

If one of those is in the log, it was OOM. (If the log shows a different error – missing model, custom node import failure, network timeout to a download – that’s a different problem; see the matching section below or in the workflow’s own Troubleshooting.)

What to do

In rough order of how much they help:

1. Close other GPU-using apps – browsers with hardware acceleration, video editors, image editors with GPU previews, games, even an idle Blender viewport with Eevee/Cycles loaded. Each can hold 1–3 GB of VRAM.
2. Reduce the workflow’s output size or batch. Lower the longest-edge target, the upscale factor, or the variation count. The biggest VRAM cost is usually the latent and VAE buffer, both of which scale with output pixels.
3. Drop unused LoRAs. Each loaded LoRA adds to peak VRAM. If a workflow lets you stack LoRAs, try with fewer.
4. Restart ComfyUI between runs. Click Stop ComfyUI in the toolbar, wait for the dot to go gray, then Start ComfyUI. Some workflows leave residual VRAM allocated even after they finish; a restart fully reclaims it.
5. If you’re consistently right at the edge, consider whether your card actually meets the workflow’s recommended VRAM (each workflow chapter lists its requirement). Some workflows (Extend Image, Trellis2, large SeedVR2 upscales) are 16 GB minimums in practice even where the card datasheet says 12 GB is enough.

Why isn’t the error message clearer?

ComfyUI’s /prompt API doesn’t return a structured error code for VRAM exhaustion – the OOM happens deep inside a model node, gets caught generically, and the workflow finishes with a non-success status that Comfy Labs surfaces as the generic “failed” banner. We’re tracking this; for now the log is the source of truth.

ComfyUI status dot stays gray after clicking a workflow

ComfyUI is lazy-spawned on the first request. Wait 10–30 seconds – the dot should go yellow (starting) then green (running). If it stays gray:

1. Click View Log – look for [PY-comfyui] lines and any ERR lines.
2. Click Start ComfyUI in the toolbar to spawn it explicitly. (If the toolbar reads Stop ComfyUI, the backend is already running – click Stop, wait a couple of seconds for the dot to go gray, then click Start to do a clean restart.)

ComfyUI crashed (red dot, crash pane appears)

The crash pane shows the captured stderr. Common causes:

• Out of memory – reduce input size or scale factor; close other GPU apps. See A workflow fails with a generic error (likely out of VRAM) for the longer checklist; the steps there work for the crash case too.
• Missing model – a model file the workflow needs isn’t on disk. Open Settings -> the affected workflow -> Download models.
• Custom node import failure – usually a Python dependency conflict; click Send Error Report and share the ZIP.

Click Restart in the crash pane to relaunch the backend (or Start ComfyUI in the toolbar). The other Comfy Labs services keep running.

GPU appears stuck or VRAM stays full after a failure

1. Click Stop ComfyUI in the toolbar – this prompts for confirmation, then frees VRAM. Click Start ComfyUI to bring the backend back up. Usually enough.
2. If the GPU itself is wedged (rare), reset the Windows display driver with Win+Ctrl+Shift+B.
3. As a last resort, close Comfy Labs (the window-close fully shuts down all subprocesses) and relaunch.

Streamlit dot is gray and Open Workflows is disabled

Streamlit failed to start. Click View Log – look for [PY-streamlit] lines. Most likely causes:

• Port 8501 in use – another app is bound to the port. Stop the other app or set COMFY_LABS_STREAMLIT_PORT to a free port before launching.
• Python venv missing – the install is corrupted. Re-run the wizard (the next launch will detect the missing venv and offer to reconfigure).

Drive moved or unmounted (Reconfigure mode)

If your install drive disappears (external SSD unplugged, drive letter reassigned, folder deleted), the next launch shows the wizard in Reconfigure mode with a yellow banner explaining what’s missing.

• If the drive is back: re-pick the same install folder; the wizard detects the existing venv and skips the bootstrap step.
• If the drive is permanently gone: pick a new install folder; the wizard re-runs the bootstrap. Your models folder, if on a different drive that’s still mounted, is preserved – you don’t need to re-download model weights.

Update check fails with “Cannot reach update server”

Check your internet connection. If you’re offline by design, dismiss the banner – update checks never block app functionality.

ComfyUI is still running after Comfy Labs quit

If you force-killed Comfy Labs.exe from Task Manager (or it crashed without cleaning up), the ComfyUI Python process can be left behind, holding the GPU and TCP port 8188. Symptoms: relaunching Comfy Labs shows the ComfyUI dot stuck at gray or red, the GPU sits at full VRAM in Task Manager, or another app reports port 8188 is in use.

A standalone helper ships next to Comfy Labs.exe:

• Force-Quit-ComfyUI.bat – double-click. (It launches Force-Quit-ComfyUI.ps1 in the same folder.)

What it does:

1. Reads your install path from %APPDATA%\Comfy Labs\config.json.
2. Lists every python.exe rooted in that install dir, plus anything bound to TCP port 8188.
3. Shows you the candidate PIDs and asks for confirmation (Y / N).
4. On Y, runs taskkill /T /F on each process tree, then re-checks port 8188 and reports whether it is free.

Safe to run any time – if no orphans are detected it prints “Nothing to do” and exits. Use it before relaunching Comfy Labs whenever you suspect a stale ComfyUI is still alive.

I need to reset everything

See Uninstall for the safe reset procedure.

Uninstall

Comfy Labs ships a standalone interactive uninstaller (Uninstall-Comfy-Labs.bat) in the same folder as Comfy Labs.exe. There are two ways to remove the app – the recommended interactive script, or fully manual PowerShell for users with non-standard installs.

Method 1 – Standalone interactive uninstaller (recommended)

Find the uninstaller

You can find Uninstall-Comfy-Labs.bat two ways:

• From inside the app: click the red Uninstall Comfy Labs button at the bottom of the welcome screen. The app does not uninstall itself – it just opens Windows Explorer with Uninstall-Comfy-Labs.bat selected and shows a dialog telling you to close Comfy Labs and double-click the .bat.
• From Explorer directly: navigate to the folder containing Comfy Labs.exe. Uninstall-Comfy-Labs.bat and Uninstall-Comfy-Labs.ps1 sit next to it. (If you would rather run the PowerShell file directly, right-click Uninstall-Comfy-Labs.ps1 -> Run with PowerShell.)

Run it

After closing Comfy Labs, double-click Uninstall-Comfy-Labs.bat. A console window opens, scans your install for size, and presents a 7-item checklist with live folder sizes:

Controls

• 1-7 – toggle that item on/off.
• A – toggle all enabled items at once.
• C – confirm and proceed (shows a final “Are you sure?” prompt).
• Q – quit without doing anything.

What it does when you confirm

1. Stops Comfy Labs.exe and any orphaned python.exe processes still rooted in your install folder. Safe to run even if the app appears to still be holding files.
2. Deletes each selected item, with retries for transiently-locked files. Items inside the Runtime folder that you chose to keep (e.g. Models with item 2 selected but item 3 unchecked) are preserved.
3. Verifies each path is gone and prints a green “removed” line per item, or a yellow warning for anything it could not fully delete.

After it finishes

If item 1 (Electron app folder) was selected and you ran the .bat from that same folder, the script can’t delete itself – it leaves only Uninstall-Comfy-Labs.bat and Uninstall-Comfy-Labs.ps1 behind, and prints You can now delete this folder: <path>. Open Explorer and delete the folder yourself.

If you linked from an existing ComfyUI install during step 4 of the wizard, those files are not deleted – the .comfy_labs_manifest.json records hardlinks vs. copies, and the uninstaller leaves your other ComfyUI install untouched.

Method 2 – Fully manual

For users whose install is in a non-standard location, or who want to script the cleanup themselves. Run the following in PowerShell, replacing <install_dir> with the folder you picked during the wizard (defaults to something like D:\Comfy-Labs) and <app_dir> with the folder containing Comfy Labs.exe:

# 1. Kill any running Comfy Labs or related Python processes
Get-Process "Comfy Labs" -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process python* -ErrorAction SilentlyContinue | Where-Object {
    $_.Path -like "<install_dir>\*"
} | Stop-Process -Force

# 2. Delete the install directory (runtime + ComfyUI + models + outputs)
Remove-Item -Recurse -Force "<install_dir>"

# 3. Delete the app config + Electron data
Remove-Item -Recurse -Force "$env:APPDATA\Comfy Labs"

# 4. Delete the pip wheel cache
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Comfy Labs\pip-cache"

# 5. Delete the Electron app folder (the folder containing Comfy Labs.exe)
Remove-Item -Recurse -Force "<app_dir>"

# 6. (Optional) Delete the HuggingFace model cache. WARNING: other AI apps
#    on your system may share this cache. Only run if you are sure.
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\huggingface"

If you have custom Models or Output folders set in Preferences that live outside <install_dir>, delete those separately.

What does NOT need cleanup

• Windows Registry – Comfy Labs writes no registry entries.
• Start Menu / Desktop shortcuts – the portable build creates none.
• Windows services – none installed.
• System PATH – not modified.
• System Python – not touched. Comfy Labs ships its own Python runtime inside the install folder.

Appendix A – Folder structure

This appendix documents both the installed app layout (what you see on your machine after running the wizard) and the dev repository layout (D:\GitHub\comfy-lab – relevant if you’re contributing or reading the source).

Installed app – what lives where

After first-run setup, Comfy Labs spans four locations on disk:

<wherever you unzipped Comfy Labs.exe>\        # Portable app (~255 MB packed)
+-- Comfy Labs.exe                              # Main executable
+-- resources\
|   +-- app\                                    # Vite-built React + Electron main
|   +-- python\                                 # Streamlit app + 9 workflow plugins
|   +-- python-bootstrap\                       # bootstrap.py + custom_nodes.txt
|   +-- python-runtime\                         # Bundled CPython 3.12.13 tarball (~46 MB)
|   +-- git-runtime\                            # Bundled MinGit 2.54.0 tarball (~40 MB)
|   \-- public\                                 # Icons, hero image, debug_logs/
+-- LICENSES.md                                 # Third-party attributions (ships next to the .exe)
+-- Uninstall-Comfy-Labs.bat / .ps1             # Standalone uninstaller (interactive 7-item checklist)
+-- Force-Quit-ComfyUI.bat / .ps1               # Hard-kill orphaned ComfyUI / Python on port 8188
\-- ...

%APPDATA%\Comfy Labs\                           # User data on C: (~10 MB total)
+-- config.json                                 # All your settings
+-- window-state.json                           # Window position + size
+-- app.log                                     # Combined log (Electron + 3 subprocesses)
\-- workflows\                                  # Manually-imported workflows (optional)
    \-- <workflow-id>\

%LOCALAPPDATA%\Comfy Labs\                      # Local-only caches (typically a few GB after a full install)
\-- pip-cache\                                  # Pip wheel cache (~4 GB after a full install). Wipeable
                                                #   from Prefs; never auto-cleaned.

<install_dir you picked>\                       # Heavy install (~21 GB), e.g. D:\Comfy-Labs\
+-- python-runtime\                             # Bundled CPython 3.12.13 (extracted on first run, ~150 MB)
|   \-- python.exe                              # Base interpreter -- never on PATH, never registered with the OS
+-- git-runtime\                                # Bundled MinGit 2.54.0 (extracted on first run, ~80 MB)
|   \-- cmd\git.exe                             # Used only by bootstrap clone steps (env var COMFY_LABS_GIT_EXE)
+-- runtime\                                    # Python venv built on top of python-runtime\python.exe
|   +-- Scripts\
|   |   \-- python.exe                          # Venv Python (PyTorch, ComfyUI deps, custom-node deps)
|   +-- Lib\site-packages\                      # All Python packages
|   \-- pyvenv.cfg
+-- comfyui\                                    # ComfyUI source (cloned at pinned commit via the bundled git)
|   +-- main.py                                 # ComfyUI entry point
|   +-- custom_nodes\                           # 26 pinned custom nodes installed here
|   \-- ...
+-- models\                                     # (default) AI model weights, see below
\-- output\                                     # (default) Generated images, meshes, etc.

<models_folder you picked>\                     # AI weights (5--70 GB, on whichever drive you picked)
+-- diffusion_models\                           # Stable Diffusion / Flux / Z-Image .safetensors
+-- clip\                                       # CLIP and T5 text encoders
+-- vae\                                        # VAE weights
+-- checkpoints\                                # Misc model checkpoints
+-- model_patches\                              # ControlNet, IP-Adapter weights
+-- inpaint\                                    # LaMa inpainting weights
+-- microsoft\                                  # Trellis2 (Image to 3D Mesh)
+-- diffusers\                                  # BiRefNet (background removal for 3D)
+-- facebook\                                   # DINOv3 feature extractor
+-- LLM\Qwen-VL\Qwen3-VL-2B-Instruct\           # QwenVL captioning model (Extend Image, HF transformers, v0.2.18+)
+-- loras\                                      # LoRA styles for Concept Magic LoRA
\-- .comfy_labs_manifest.json                   # Provenance: which files came from where
                                                # (so uninstall doesn't delete linked-from-existing files)

Why so many separate locations?

This split is deliberate: app updates are small and fast (replace the .exe folder), while the heavy stuff (runtime, models, outputs, pip cache) is preserved across updates. The bundled-runtime tarballs in the app folder are the source-of-truth for first-run extraction; once they have been unpacked into <install_dir> once, app updates do not touch them again.

Appendix B – File reference

A quick index of the most useful files, grouped by what you’d come looking for.

“I want to change a setting”

“Something broke; I need logs”

“I want to understand what subprocess does what”

All three log to the same app.log with [PY-streamlit], [PY-cmBridge], [PY-comfyui] prefixes (errors get an extra ERR tag).

“I want to install or update a workflow”

The Settings page inside the Streamlit pane is the supported path: open the app -> Open Workflows -> sidebar -> Settings.

For developers / advanced users:

“I want to drive the app from Claude Code (or any external tool)”