# ComfyUI — Run on fal.ai

A simple local launcher that connects your ComfyUI interface to a serverless GPU on fal.ai.

---

## Start here

### macOS
Double-click **`ComfyUI.command`**

> **First time?** macOS may show "can't be opened, unidentified developer".
> **Workaround**: right-click `ComfyUI.command` → **Open** → **Open** in the dialog.

> macOS will also ask "**Python wants to accept incoming connections**". Click **Allow**
> (the proxy only binds `localhost`, nothing is exposed to the network).

### Windows
Double-click **`ComfyUI.bat`**

> Requires **Python 3.11** from https://www.python.org/downloads/ —
> during install, **check "Add Python to PATH"**.

---

## What happens

1. **First run** installs Python dependencies in a local `.venv/` (1–2 min, one-time).
2. A browser tab opens on **http://localhost:9998** — that's the launcher UI.
3. Enter your **FAL API Key** (https://fal.ai/dashboard/keys) and the **endpoint** your team lead gave you (e.g. `my-team/comfy`). Saved to `.env`, you won't be asked again.
4. Click **Start ComfyUI**. After a few seconds a new tab opens on **http://localhost:8188** with the full ComfyUI interface.

Your workflows run on fal.ai cloud GPUs. Outputs are saved locally under `userdata/` and also visible in the admin UI's Outputs tab.

---

## Heads up

- **Cold start**: the first workflow of the day can take **5–10 minutes** to warm up the GPU (downloading models + custom nodes). Subsequent runs are fast. This is normal — don't close the window.
- **Reconnecté toasts** in the ComfyUI UI are cosmetic. Your workflow still runs.
- **Close the launcher** terminal window to shut down the proxy.

---

## Advanced

The old terminal-based script is still available:

- `./run.sh` (mac/linux) or `run.bat` / `run.ps1` (windows)

This skips the GUI and runs the proxy directly.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| macOS `"cannot be opened"` warning | Right-click → **Open** → **Open** |
| Windows `python is not recognized` | Install Python 3.11 with "Add Python to PATH" |
| Browser shows "This site can't be reached" on :8188 | The runner is still cold-starting. Wait a few minutes. |
| "Reconnecté" toasts in ComfyUI | Cosmetic; your workflow still runs. Ignore. |
| Port already in use | Close the existing terminal window; the launcher auto-kills stale instances on next start. |

Full guide: [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)
