ComfyUI Integration

ComfyUI Integration

Sweet Tea is the creative workspace; ComfyUI is the engine that generates your images. This chapter covers how they connect, what the health states mean, and how to diagnose problems when the connection isn't cooperating.

How the Connection Works

Studio communicates with ComfyUI over two channels:

• REST API for queuing jobs, reading settings, and fetching metadata
• WebSocket for live progress updates during generation

Both need to be working for a smooth experience. If you can queue a job but don't see live progress updates, the issue is usually WebSocket-specific — check firewalls, proxies, or networking configuration before changing workflow settings.

Managed vs. External Runtime

You have two ways to connect Studio to ComfyUI. Choose based on how much control you want over the runtime.

Managed runtime (recommended for most users)

Studio starts, stops, and monitors ComfyUI for you. You point it at your ComfyUI installation directory, and it handles the rest.

Best when: You want convenience and fewer moving parts. Studio manages the process lifecycle and gives you logs and status without you touching a terminal.

Setup:

1. Open Settings > Engine.
2. Set the ComfyUI path to your ComfyUI directory.
3. Optionally configure launch arguments (like --listen or --gpu-only).
4. Click Start or let Studio auto-start on launch.
5. Watch the status bar — when it turns healthy, you're ready.

External runtime

Studio connects to a ComfyUI instance you're running independently.

Best when: You have a custom ComfyUI setup with specific environment controls, or you're connecting to a remote instance (like a hosted GPU — see Hosted GPU Workflows).

Setup:

1. Start ComfyUI yourself however you normally would.
2. Open Settings > Engine.
3. Enter the ComfyUI URL (default: http://127.0.0.1:8188).
4. Studio connects and begins health monitoring.

Tip: You can switch between managed and external runtime anytime. If you're troubleshooting, switching to external mode and running ComfyUI manually gives you more visibility into startup logs.

Health States

The status bar at the bottom of Studio always shows the current engine state. Here's what each state means and what to do:

Note: Don't try to "fix" a Disconnected state by editing prompts or workflow settings. The issue is almost always in the connection configuration or the ComfyUI process itself, not in your creative settings.

Setting Up the Managed Runtime Step by Step

If you're using the managed path and it's your first time:

1. Open Settings > Engine and set your ComfyUI directory path.
2. Verify the path is correct — the directory should contain ComfyUI's main.py or equivalent entry point.
3. Add any launch arguments you need (most users can skip this).
4. Click Start.
5. Watch the status bar transition from Starting to Connected.
6. Run one simple test generation in Prompt Studio to confirm end-to-end health.

Only move on to importing complex workflows once this baseline works.

Connecting to an External Instance

1. Make sure ComfyUI is running and accessible.
2. In Settings > Engine, enter the URL (e.g., http://127.0.0.1:8188).
3. Studio should connect within a few seconds.
4. If it doesn't, verify:
   • ComfyUI is running and not erroring on startup
   • The port isn't blocked by a firewall
   • If remote, that the host and port are reachable from your machine

Diagnosis Quick Reference

When something isn't working, this table helps you narrow down the cause fast:

Tip: Engine logs are your best friend when debugging connection issues. In Settings, look for the log viewer that shows ComfyUI's stdout and stderr output. The error message is usually right there.

Next: Prompt Studio