> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runchat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ComfyUI

> Queue ComfyUI workflows on your own GPU, a local PC or a rented VM like Vast.ai or RunPod, and bring the images back onto the canvas

If you already run [ComfyUI](https://github.com/comfyanonymous/ComfyUI), Runchat can drive it. Two [Code](https://docs.runchat.com/node-reference/nodes/code.md) nodes send a workflow to ComfyUI's HTTP API and bring the images back onto the canvas. Your checkpoints, LoRAs and custom nodes do the generating on your own hardware, and the results can feed any other node in your Runchat workflow.

**You'll need:** a running ComfyUI server, on your own machine or a cloud GPU (Vast.ai, RunPod, or any VM)

> **[Open the example workflow](https://runchat.com/editor?id=b5ce86b0-fe4c-4e76-b7e7-a6ecddde5820)**
>
> Make a copy of this workflow in your account to follow along.

## How it works

Code nodes run on Runchat's servers, not in your browser. So Runchat has to reach ComfyUI over the public internet. `localhost:8188` on your PC is not reachable from there.

The example workflow has three inputs and two code nodes:

| Node | What it does |
| - | - |
| **ComfyUI server URL** | The public address of your ComfyUI server |
| **Prompt** | Text inserted into the workflow wherever it contains `$prompt` |
| **Workflow (API format)** | A ComfyUI workflow exported as API JSON |
| **Queue prompt** | Fills in the placeholders and `POST`s the workflow to `/prompt`. Outputs the `prompt_id` |
| **Get images** | Polls `/history/{prompt_id}` until the job finishes, then downloads each saved image from `/view` |

Images come back as data URLs, which Runchat uploads automatically. They render on the node and can connect to any image input downstream.

## 1. Give ComfyUI a public hostname

Pick the option that matches where ComfyUI runs.

**Local PC (tunnel)**

The easiest and safest option is a [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). You don't need an account or router changes, and you don't have to open a port.

1. Install `cloudflared` ([downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/))
2. With ComfyUI running, start a tunnel to it:

```bash theme={null}
cloudflared tunnel --url http://localhost:8188
```

3. Copy the `https://….trycloudflare.com` URL it prints. That's your server URL.

The URL changes each time you start the tunnel and stops working when you close it.

**Vast.ai / RunPod**

Cloud GPU providers already give you a public address for ComfyUI:

* **RunPod**: use the pod's proxy URL for port 8188, e.g. `https://<pod-id>-8188.proxy.runpod.net`
* **Vast.ai**: use the HTTPS tunnel link from the instance portal if the template provides one. Otherwise use the public IP and the external port mapped to 8188 (see the IP address note below)
* **Any other VM**: start ComfyUI with `--listen 0.0.0.0`, open the port in the firewall, and use the machine's hostname

If the provider puts ComfyUI behind a login or token, see [Adding authentication](#adding-authentication).

**Port forwarding**

You can forward port 8188 on your router to your PC and start ComfyUI with `--listen 0.0.0.0`. This exposes ComfyUI to anyone who finds your IP address, and ComfyUI has no password of its own, so a tunnel is the better option.

> [!WARNING]
>
> **Bare IP addresses are blocked.** Code nodes can't `fetch()` a URL like `http://203.0.113.7:8188`. Wrap the IP in a free wildcard DNS name instead: replace the dots with dashes and add `.sslip.io`, e.g. `http://203-0-113-7.sslip.io:8188`. Custom ports work.

Paste the URL into the **ComfyUI server URL** input node.

## 2. Export your workflow in API format

ComfyUI has two JSON formats. Runchat needs the **API** one.

1. In ComfyUI, open the workflow you want to run and check that it works there
2. Choose **Workflow → Export (API)** to save the `.json` file
3. Paste its contents into the **Workflow (API format)** input node

Then mark the values Runchat should fill in:

* Replace the positive prompt text with `$prompt`. It can sit inside a longer string, e.g. `"$prompt, golden hour, 35mm"`
* Replace the seed value with `"$seed"` (as a string, including the quotes) to get a new random seed on every run

```json theme={null}
"6": {
  "class_type": "CLIPTextEncode",
  "inputs": { "text": "$prompt", "clip": ["4", 1] }
}
```

The example's default workflow is a basic Stable Diffusion 1.5 text-to-image graph. It expects the `v1-5-pruned-emaonly-fp16.safetensors` checkpoint. Change `ckpt_name` to a model you have installed.

## 3. Run it

Select **Get images** and click **Run**. Runchat runs **Queue prompt** first, then waits for the result.

**Get images** waits up to about 50 seconds, because code nodes time out after 60. If your workflow takes longer, the node stops with *Still generating*. ComfyUI keeps working, so run **Get images** on its own again to collect the images. That doesn't queue a new job.

> [!NOTE]
>
> The GPU time is yours, so ComfyUI runs cost no model credits. Each `fetch()` a code node makes costs 1 credit: one to queue, one per status check (the node backs off from 2 to 8 seconds between checks), and one per image downloaded. A typical 20-second generation uses about 5 credits plus the node run cost.

Prompts, LLM nodes, lists and loops all work as usual. Connect a list of prompts to **Prompt** and the workflow runs once per item. Or have an [Agent](https://docs.runchat.com/node-reference/nodes/agent.md) node write variations first.

## Adding authentication

ComfyUI has no login, so anyone who has your URL can queue jobs and see your outputs. A quick-tunnel URL is hard to guess and only lives while the tunnel runs. That's fine for a working session, but don't post it anywhere.

For a server that stays up, put ComfyUI behind a proxy that checks a token. Your provider may already do this, or you can set up [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/), Caddy or nginx. Then store the token as a [credential](https://docs.runchat.com/concepts/integrations/credentials.md), with its allowed origin set to your server URL, and send it from **both** code nodes:

```js theme={null}
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${ENV.comfyui_token}`,
};

const res = await fetch(`${base}/prompt`, { method: "POST", headers, body: JSON.stringify(body) });
```

Add the same `Authorization` header to the `/history` and `/view` requests in **Get images**. Or select the code nodes and ask the agent to do it.

## Troubleshooting

| Error | Cause |
| - | - |
| `error code: 1003` or *Bare IP addresses are blocked* | The URL is an IP address. Use a tunnel URL or an `sslip.io` hostname |
| *ComfyUI rejected the workflow (400): Prompt outputs failed validation* | A model, LoRA or custom node in the workflow isn't installed on that server. Check the message for the node and value |
| *ComfyUI rejected the workflow* with HTML in the message | The URL points at a login page or the wrong port, not the ComfyUI API |
| *Still generating* | The job takes more than 50 seconds. Run **Get images** again |
| No images returned | The workflow has no **Save Image** node. **Preview Image** outputs are temporary and skipped |
| Fetch fails or times out | The tunnel or VM is down, or ComfyUI isn't listening on that port. Open `<your-url>/system_stats` in a browser to check |

## Going further

Select either code node and ask the agent to extend it. For example:

* **Image-to-image**: upload an input image to ComfyUI's `/upload/image` endpoint and set its filename on a `LoadImage` node
* **More parameters**: add inputs for steps, CFG or resolution and substitute them the same way as `$prompt`
* **Publish as a tool**: [publish the workflow](https://docs.runchat.com/concepts/publishing/agent-tools.md) so the agent can call your ComfyUI setup directly from chat

## Next steps

* [Code node](https://docs.runchat.com/node-reference/nodes/code.md): the sandbox, inputs and outputs
* [Credentials](https://docs.runchat.com/concepts/integrations/credentials.md): store tokens for your server securely
* [Text-to-image ideation](https://docs.runchat.com/examples/text-to-image-ideation.md): compare your local models against hosted ones


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.